<html><head>
      <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
   <title>16.&nbsp;View technologies</title><link rel="stylesheet" href="css/stylesheet.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.74.0"><link rel="home" href="index.html" title="Reference Documentation"><link rel="up" href="spring-web.html" title="Part&nbsp;V.&nbsp;The Web"><link rel="prev" href="mvc.html" title="15.&nbsp;Web MVC framework"><link rel="next" href="web-integration.html" title="17.&nbsp;Integrating with other web frameworks"><!--Begin Google Analytics code--><script type="text/javascript">
			var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www.");
			document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E"));
		</script><script type="text/javascript">
			var pageTracker = _gat._getTracker("UA-2728886-3");
			pageTracker._setDomainName("none");
			pageTracker._setAllowLinker(true);
			pageTracker._trackPageview();
		</script><!--End Google Analytics code--></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">16.&nbsp;View technologies</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="mvc.html">Prev</a>&nbsp;</td><th width="60%" align="center">Part&nbsp;V.&nbsp;The Web</th><td width="20%" align="right">&nbsp;<a accesskey="n" href="web-integration.html">Next</a></td></tr></table><hr></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="view"></a>16.&nbsp;View technologies</h2></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="view-introduction"></a>16.1&nbsp;Introduction</h2></div></div></div><p>One of the areas in which Spring excels is in the separation of view
    technologies from the rest of the MVC framework. For example, deciding to
    use Velocity or XSLT in place of an existing JSP is primarily a matter of
    configuration. This chapter covers the major view technologies that work
    with Spring and touches briefly on how to add new ones. This chapter
    assumes you are already familiar with <a class="xref" href="mvc.html#mvc-viewresolver" title="15.5&nbsp;Resolving views">Section&nbsp;15.5, &#8220;Resolving views&#8221;</a>
    which covers the basics of how views in general are coupled to the MVC
    framework.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="view-jsp"></a>16.2&nbsp;JSP &amp; JSTL</h2></div></div></div><p>Spring provides a couple of out-of-the-box solutions for JSP and
    JSTL views. Using JSP or JSTL is done using a normal view resolver defined
    in the <code class="interfacename">WebApplicationContext</code>. Furthermore,
    of course you need to write some JSPs that will actually render the
    view.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.gif"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p>
        Setting up your application to use JSTL is a common source of error,
        mainly caused by confusion over the different servlet spec., JSP and JSTL
        version numbers, what they mean and how to declare the taglibs correctly. 
        The article
        <a class="ulink" href="http://www.mularien.com/blog/2008/04/24/how-to-reference-and-use-jstl-in-your-web-application/" target="_top">
        How to Reference and Use JSTL in your Web Application</a> provides a 
        useful guide to the common pitfalls and how to avoid them. Note that as of
        Spring 3.0, the minimum supported servlet version is 2.4 (JSP 2.0 and JSTL 1.1),
        which reduces the scope for confusion somewhat.
      </p></td></tr></table></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="view-jsp-resolver"></a>16.2.1&nbsp;View resolvers</h3></div></div></div><p>Just as with any other view technology you're integrating with
      Spring, for JSPs you'll need a view resolver that will resolve your
      views. The most commonly used view resolvers when developing with JSPs
      are the <code class="classname">InternalResourceViewResolver</code> and the
      <code class="classname">ResourceBundleViewResolver</code>. Both are declared in
      the <code class="interfacename">WebApplicationContext</code>:</p><pre class="programlisting">&lt;<span class="hl-comment">!-- the ResourceBundleViewResolver --</span>&gt;
&lt;<span class="hl-tag">bean</span> <span class="hl-attribute">id</span>=<span class="hl-value">"viewResolver"</span> <span class="hl-attribute">class</span>=<span class="hl-value">"org.springframework.web.servlet.view.ResourceBundleViewResolver"</span>&gt;
  &lt;<span class="hl-tag">property</span> <span class="hl-attribute">name</span>=<span class="hl-value">"basename"</span> <span class="hl-attribute">value</span>=<span class="hl-value">"views"</span>/&gt;
&lt;<span class="hl-tag">/bean</span>&gt;

# And a sample properties file is uses (views.properties in WEB-INF/classes):
welcome.(class)=org.springframework.web.servlet.view.JstlView
welcome.url=/WEB-INF/jsp/welcome.jsp

productList.(class)=org.springframework.web.servlet.view.JstlView
productList.url=/WEB-INF/jsp/productlist.jsp</pre><p>As you can see, the
      <code class="classname">ResourceBundleViewResolver</code> needs a properties
      file defining the view names mapped to 1) a class and 2) a URL. With a
      <code class="classname">ResourceBundleViewResolver</code> you can mix different
      types of views using only one resolver.</p><pre class="programlisting">&lt;<span class="hl-tag">bean</span> <span class="hl-attribute">id</span>=<span class="hl-value">"viewResolver"</span> <span class="hl-attribute">class</span>=<span class="hl-value">"org.springframework.web.servlet.view.InternalResourceViewResolver"</span>&gt;
  &lt;<span class="hl-tag">property</span> <span class="hl-attribute">name</span>=<span class="hl-value">"viewClass"</span> <span class="hl-attribute">value</span>=<span class="hl-value">"org.springframework.web.servlet.view.JstlView"</span>/&gt;
  &lt;<span class="hl-tag">property</span> <span class="hl-attribute">name</span>=<span class="hl-value">"prefix"</span> <span class="hl-attribute">value</span>=<span class="hl-value">"/WEB-INF/jsp/"</span>/&gt;
  &lt;<span class="hl-tag">property</span> <span class="hl-attribute">name</span>=<span class="hl-value">"suffix"</span> <span class="hl-attribute">value</span>=<span class="hl-value">".jsp"</span>/&gt;
&lt;<span class="hl-tag">/bean</span>&gt;</pre><p>The <code class="classname">InternalResourceBundleViewResolver</code> can
      be configured for using JSPs as described above. As a best practice, we
      strongly encourage placing your JSP files in a directory under the
      <code class="filename">'WEB-INF'</code> directory, so there can
      be no direct access by clients.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="view-jsp-jstl"></a>16.2.2&nbsp;'Plain-old' JSPs versus JSTL</h3></div></div></div><p>When using the Java Standard Tag Library you must use a special
      view class, the <code class="classname">JstlView</code>, as JSTL needs some
      preparation before things such as the I18N features will work.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="view-jsp-tags"></a>16.2.3&nbsp;Additional tags facilitating development</h3></div></div></div><p>Spring provides data binding of request parameters to command
      objects as described in earlier chapters. To facilitate the development
      of JSP pages in combination with those data binding features, Spring
      provides a few tags that make things even easier. All Spring tags have
      <span class="emphasis"><em>HTML escaping</em></span> features to enable or disable
      escaping of characters.</p><p>The tag library descriptor (TLD) is included in the <code class="filename">spring-webmvc.jar</code>.
      Further information about the individual tags can be found in
      the appendix entitled <a class="xref" href="spring.tld.html" title="Appendix&nbsp;F.&nbsp;spring.tld">Appendix&nbsp;F, <i>spring.tld</i></a>.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="view-jsp-formtaglib"></a>16.2.4&nbsp;Using Spring's form tag library</h3></div></div></div><p>As of version 2.0, Spring provides a comprehensive set of data
      binding-aware tags for handling form elements when using JSP and Spring
      Web MVC. Each tag provides support for the set of attributes of its
      corresponding HTML tag counterpart, making the tags familiar and
      intuitive to use. The tag-generated HTML is HTML 4.01/XHTML 1.0
      compliant.</p><p>Unlike other form/input tag libraries, Spring's form tag library
      is integrated with Spring Web MVC, giving the tags access to the command
      object and reference data your controller deals with. As you will see in
      the following examples, the form tags make JSPs easier to develop, read
      and maintain.</p><p>Let's go through the form tags and look at an example of how each
      tag is used. We have included generated HTML snippets where certain tags
      require further commentary.</p><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="view-jsp-formtaglib-configuration"></a>16.2.4.1&nbsp;Configuration</h4></div></div></div><p>The form tag library comes bundled in
        <code class="literal">spring-webmvc.jar</code>.
        The library descriptor is called
        <code class="literal">spring-form.tld</code>.</p><p>To use the tags from this library, add the following directive
        to the top of your JSP page:</p><pre class="programlisting">&lt;<span class="hl-tag">%@</span> <span class="hl-attribute">taglib</span> <span class="hl-attribute">prefix</span>=<span class="hl-value">"form"</span> <span class="hl-attribute">uri</span>=<span class="hl-value">"http://www.springframework.org/tags/form"</span> <span class="hl-attribute">%&gt;</span></pre><p>... where <code class="literal">form</code> is the tag name prefix you
        want to use for the tags from this library.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="view-jsp-formtaglib-formtag"></a>16.2.4.2&nbsp;The <code class="literal">form</code> tag</h4></div></div></div><p>This tag renders an HTML 'form' tag and exposes a binding path
        to inner tags for binding. It puts the command object in the
        <code class="literal">PageContext</code> so that the command object can be
        accessed by inner tags. <span class="emphasis"><em>All the other tags in this library
        are nested tags of the <code class="literal">form</code> tag</em></span>.</p><p>Let's assume we have a domain object called
        <code class="classname">User</code>. It is a JavaBean with properties such as
        <code class="literal">firstName</code> and <code class="literal">lastName</code>. We will
        use it as the form backing object of our form controller which returns
        <code class="literal">form.jsp</code>. Below is an example of what
        <code class="literal">form.jsp</code> would look like:</p><pre class="programlisting">&lt;<span class="hl-tag">form:form</span>&gt;
      &lt;<span class="hl-tag">table</span>&gt;
          &lt;<span class="hl-tag">tr</span>&gt;
              &lt;<span class="hl-tag">td</span>&gt;First Name:&lt;<span class="hl-tag">/td</span>&gt;
              &lt;<span class="hl-tag">td</span>&gt;&lt;<span class="hl-tag">form:input</span> <span class="hl-attribute">path</span>=<span class="hl-value">"firstName"</span> /&gt;&lt;<span class="hl-tag">/td</span>&gt;
          &lt;<span class="hl-tag">/tr</span>&gt;
          &lt;<span class="hl-tag">tr</span>&gt;
              &lt;<span class="hl-tag">td</span>&gt;Last Name:&lt;<span class="hl-tag">/td</span>&gt;
              &lt;<span class="hl-tag">td</span>&gt;&lt;<span class="hl-tag">form:input</span> <span class="hl-attribute">path</span>=<span class="hl-value">"lastName"</span> /&gt;&lt;<span class="hl-tag">/td</span>&gt;
          &lt;<span class="hl-tag">/tr</span>&gt;
          &lt;<span class="hl-tag">tr</span>&gt;
              &lt;<span class="hl-tag">td</span> <span class="hl-attribute">colspan</span>=<span class="hl-value">"2"</span>&gt;
                  &lt;<span class="hl-tag">input</span> <span class="hl-attribute">type</span>=<span class="hl-value">"submit"</span> <span class="hl-attribute">value</span>=<span class="hl-value">"Save Changes"</span> /&gt;
              &lt;<span class="hl-tag">/td</span>&gt;
          &lt;<span class="hl-tag">/tr</span>&gt;
      &lt;<span class="hl-tag">/table</span>&gt;
  &lt;<span class="hl-tag">/form:form</span>&gt;</pre><p>The <code class="literal">firstName</code> and <code class="literal">lastName</code>
        values are retrieved from the command object placed in the
        <code class="interfacename">PageContext</code> by the page controller.
        Keep reading to see more complex examples of how inner tags are used
        with the <code class="literal">form</code> tag.</p><p>The generated HTML looks like a standard form:</p><pre class="programlisting">&lt;<span class="hl-tag">form</span> <span class="hl-attribute">method</span>=<span class="hl-value">"POST"</span>&gt;
      &lt;<span class="hl-tag">table</span>&gt;
        &lt;<span class="hl-tag">tr</span>&gt;
            &lt;<span class="hl-tag">td</span>&gt;First Name:&lt;<span class="hl-tag">/td</span>&gt;
            &lt;<span class="hl-tag">td</span>&gt;&lt;<span class="hl-tag">input</span> <span class="hl-attribute">name</span>=<span class="hl-value">"firstName"</span> <span class="hl-attribute">type</span>=<span class="hl-value">"text"</span> <span class="hl-attribute">value</span>=<span class="hl-value">"Harry"</span>/&gt;&lt;<span class="hl-tag">/td</span>&gt;
        &lt;<span class="hl-tag">/tr</span>&gt;
        &lt;<span class="hl-tag">tr</span>&gt;
            &lt;<span class="hl-tag">td</span>&gt;Last Name:&lt;<span class="hl-tag">/td</span>&gt;
            &lt;<span class="hl-tag">td</span>&gt;&lt;<span class="hl-tag">input</span> <span class="hl-attribute">name</span>=<span class="hl-value">"lastName"</span> <span class="hl-attribute">type</span>=<span class="hl-value">"text"</span> <span class="hl-attribute">value</span>=<span class="hl-value">"Potter"</span>/&gt;&lt;<span class="hl-tag">/td</span>&gt;
        &lt;<span class="hl-tag">/tr</span>&gt;
        &lt;<span class="hl-tag">tr</span>&gt;
            &lt;<span class="hl-tag">td</span> <span class="hl-attribute">colspan</span>=<span class="hl-value">"2"</span>&gt;
              &lt;<span class="hl-tag">input</span> <span class="hl-attribute">type</span>=<span class="hl-value">"submit"</span> <span class="hl-attribute">value</span>=<span class="hl-value">"Save Changes"</span> /&gt;
            &lt;<span class="hl-tag">/td</span>&gt;
        &lt;<span class="hl-tag">/tr</span>&gt;
      &lt;<span class="hl-tag">/table</span>&gt;
  &lt;<span class="hl-tag">/form</span>&gt;</pre><p>The preceding JSP assumes that the variable name of the form
        backing object is <code class="literal">'command'</code>. If you have put the
        form backing object into the model under another name (definitely a
        best practice), then you can bind the form to the named variable like
        so:</p><pre class="programlisting">&lt;<span class="hl-tag">form:form</span> <span class="hl-attribute">commandName</span>=<span class="hl-value">"user"</span>&gt;
      &lt;<span class="hl-tag">table</span>&gt;
          &lt;<span class="hl-tag">tr</span>&gt;
              &lt;<span class="hl-tag">td</span>&gt;First Name:&lt;<span class="hl-tag">/td</span>&gt;
              &lt;<span class="hl-tag">td</span>&gt;&lt;<span class="hl-tag">form:input</span> <span class="hl-attribute">path</span>=<span class="hl-value">"firstName"</span> /&gt;&lt;<span class="hl-tag">/td</span>&gt;
          &lt;<span class="hl-tag">/tr</span>&gt;
          &lt;<span class="hl-tag">tr</span>&gt;
              &lt;<span class="hl-tag">td</span>&gt;Last Name:&lt;<span class="hl-tag">/td</span>&gt;
              &lt;<span class="hl-tag">td</span>&gt;&lt;<span class="hl-tag">form:input</span> <span class="hl-attribute">path</span>=<span class="hl-value">"lastName"</span> /&gt;&lt;<span class="hl-tag">/td</span>&gt;
          &lt;<span class="hl-tag">/tr</span>&gt;
          &lt;<span class="hl-tag">tr</span>&gt;
              &lt;<span class="hl-tag">td</span> <span class="hl-attribute">colspan</span>=<span class="hl-value">"2"</span>&gt;
                  &lt;<span class="hl-tag">input</span> <span class="hl-attribute">type</span>=<span class="hl-value">"submit"</span> <span class="hl-attribute">value</span>=<span class="hl-value">"Save Changes"</span> /&gt;
              &lt;<span class="hl-tag">/td</span>&gt;
          &lt;<span class="hl-tag">/tr</span>&gt;
      &lt;<span class="hl-tag">/table</span>&gt;
  &lt;<span class="hl-tag">/form:form</span>&gt;</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="view-jsp-formtaglib-inputtag"></a>16.2.4.3&nbsp;The <code class="literal">input</code> tag</h4></div></div></div><p>This tag renders an HTML 'input' tag with type 'text' using the
        bound value. For an example of this tag, see <a class="xref" href="view.html#view-jsp-formtaglib-formtag" title="16.2.4.2&nbsp;The form tag">Section&nbsp;16.2.4.2, &#8220;The form tag&#8221;</a>.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="view-jsp-formtaglib-checkboxtag"></a>16.2.4.4&nbsp;The <code class="literal">checkbox</code> tag</h4></div></div></div><p>This tag renders an HTML 'input' tag with type
        'checkbox'.</p><p>Let's assume our <code class="classname">User</code> has preferences
        such as newsletter subscription and a list of hobbies. Below is an
        example of the <code class="classname">Preferences</code> class:</p><pre class="programlisting"><span class="hl-keyword">public</span> <span class="hl-keyword">class</span> Preferences {

      <span class="hl-keyword">private</span> <span class="hl-keyword">boolean</span> receiveNewsletter;

      <span class="hl-keyword">private</span> String[] interests;

      <span class="hl-keyword">private</span> String favouriteWord;

      <span class="hl-keyword">public</span> <span class="hl-keyword">boolean</span> isReceiveNewsletter() {
          <span class="hl-keyword">return</span> receiveNewsletter;
      }

      <span class="hl-keyword">public</span> <span class="hl-keyword">void</span> setReceiveNewsletter(<span class="hl-keyword">boolean</span> receiveNewsletter) {
          <span class="hl-keyword">this</span>.receiveNewsletter = receiveNewsletter;
      }

      <span class="hl-keyword">public</span> String[] getInterests() {
          <span class="hl-keyword">return</span> interests;
      }

      <span class="hl-keyword">public</span> <span class="hl-keyword">void</span> setInterests(String[] interests) {
          <span class="hl-keyword">this</span>.interests = interests;
      }

      <span class="hl-keyword">public</span> String getFavouriteWord() {
          <span class="hl-keyword">return</span> favouriteWord;
      }

      <span class="hl-keyword">public</span> <span class="hl-keyword">void</span> setFavouriteWord(String favouriteWord) {
          <span class="hl-keyword">this</span>.favouriteWord = favouriteWord;
      }
  }</pre><p>The <code class="literal">form.jsp</code> would look like:</p><pre class="programlisting">&lt;<span class="hl-tag">form:form</span>&gt;
      &lt;<span class="hl-tag">table</span>&gt;
          &lt;<span class="hl-tag">tr</span>&gt;
              &lt;<span class="hl-tag">td</span>&gt;Subscribe to newsletter?:&lt;<span class="hl-tag">/td</span>&gt;
              &lt;<span class="hl-tag">%--</span> <span class="hl-attribute">Approach</span> <span class="hl-attribute">1:</span> <span class="hl-attribute">Property</span> <span class="hl-attribute">is</span> <span class="hl-attribute">of</span> <span class="hl-attribute">type</span> <span class="hl-attribute">java.lang.Boolean</span> <span class="hl-attribute">--%&gt;</span>
              <span class="hl-attribute">&lt;td&gt;&lt;form:checkbox</span> <span class="hl-attribute">path</span>=<span class="hl-value">"preferences.receiveNewsletter"</span>/&gt;&lt;<span class="hl-tag">/td</span>&gt;
          &lt;<span class="hl-tag">/tr</span>&gt;

          &lt;<span class="hl-tag">tr</span>&gt;
              &lt;<span class="hl-tag">td</span>&gt;Interests:&lt;<span class="hl-tag">/td</span>&gt;
              &lt;<span class="hl-tag">td</span>&gt;
                  &lt;<span class="hl-tag">%--</span> <span class="hl-attribute">Approach</span> <span class="hl-attribute">2:</span> <span class="hl-attribute">Property</span> <span class="hl-attribute">is</span> <span class="hl-attribute">of</span> <span class="hl-attribute">an</span> <span class="hl-attribute">array</span> <span class="hl-attribute">or</span> <span class="hl-attribute">of</span> <span class="hl-attribute">type</span> <span class="hl-attribute">java.util.Collection</span> <span class="hl-attribute">--%&gt;</span>
                  <span class="hl-attribute">Quidditch:</span> <span class="hl-attribute">&lt;form:checkbox</span> <span class="hl-attribute">path</span>=<span class="hl-value">"preferences.interests"</span> <span class="hl-attribute">value</span>=<span class="hl-value">"Quidditch"</span>/&gt;
                  Herbology: &lt;<span class="hl-tag">form:checkbox</span> <span class="hl-attribute">path</span>=<span class="hl-value">"preferences.interests"</span> <span class="hl-attribute">value</span>=<span class="hl-value">"Herbology"</span>/&gt;
                  Defence Against the Dark Arts: &lt;<span class="hl-tag">form:checkbox</span> <span class="hl-attribute">path</span>=<span class="hl-value">"preferences.interests"</span>
                      <span class="hl-attribute">value</span>=<span class="hl-value">"Defence Against the Dark Arts"</span>/&gt;
              &lt;<span class="hl-tag">/td</span>&gt;
          &lt;<span class="hl-tag">/tr</span>&gt;
          &lt;<span class="hl-tag">tr</span>&gt;
              &lt;<span class="hl-tag">td</span>&gt;Favourite Word:&lt;<span class="hl-tag">/td</span>&gt;
              &lt;<span class="hl-tag">td</span>&gt;
                  &lt;<span class="hl-tag">%--</span> <span class="hl-attribute">Approach</span> <span class="hl-attribute">3:</span> <span class="hl-attribute">Property</span> <span class="hl-attribute">is</span> <span class="hl-attribute">of</span> <span class="hl-attribute">type</span> <span class="hl-attribute">java.lang.Object</span> <span class="hl-attribute">--%&gt;</span>
                  <span class="hl-attribute">Magic:</span> <span class="hl-attribute">&lt;form:checkbox</span> <span class="hl-attribute">path</span>=<span class="hl-value">"preferences.favouriteWord"</span> <span class="hl-attribute">value</span>=<span class="hl-value">"Magic"</span>/&gt;
              &lt;<span class="hl-tag">/td</span>&gt;
          &lt;<span class="hl-tag">/tr</span>&gt;
      &lt;<span class="hl-tag">/table</span>&gt;
  &lt;<span class="hl-tag">/form:form</span>&gt;</pre><p>There are 3 approaches to the <code class="literal">checkbox</code> tag
      which should meet all your checkbox needs.</p><div class="itemizedlist"><ul type="disc"><li><p>Approach One - When the bound value is of type
            <code class="literal">java.lang.Boolean</code>, the
            <code class="literal">input(checkbox)</code> is marked as 'checked' if the
            bound value is <code class="literal">true</code>. The
            <code class="literal">value</code> attribute corresponds to the resolved
            value of the <code class="literal">setValue(Object)</code> value
            property.</p></li><li><p>Approach Two - When the bound value is of type
            <code class="literal">array</code> or
            <code class="interfacename">java.util.Collection</code>, the
            <code class="literal">input(checkbox)</code> is marked as 'checked' if the
            configured <code class="literal">setValue(Object)</code> value is present in
            the bound <code class="interfacename">Collection</code>.</p></li><li><p>Approach Three - For any other bound value type, the
            <code class="literal">input(checkbox)</code> is marked as 'checked' if the
            configured <code class="literal">setValue(Object)</code> is equal to the
            bound value.</p></li></ul></div><p>Note that regardless of the approach, the same HTML structure is
      generated. Below is an HTML snippet of some checkboxes:</p><pre class="programlisting">&lt;<span class="hl-tag">tr</span>&gt;
      &lt;<span class="hl-tag">td</span>&gt;Interests:&lt;<span class="hl-tag">/td</span>&gt;
      &lt;<span class="hl-tag">td</span>&gt;
          Quidditch: &lt;<span class="hl-tag">input</span> <span class="hl-attribute">name</span>=<span class="hl-value">"preferences.interests"</span> <span class="hl-attribute">type</span>=<span class="hl-value">"checkbox"</span> <span class="hl-attribute">value</span>=<span class="hl-value">"Quidditch"</span>/&gt;
          &lt;<span class="hl-tag">input</span> <span class="hl-attribute">type</span>=<span class="hl-value">"hidden"</span> <span class="hl-attribute">value</span>=<span class="hl-value">"1"</span> <span class="hl-attribute">name</span>=<span class="hl-value">"_preferences.interests"</span>/&gt;
          Herbology: &lt;<span class="hl-tag">input</span> <span class="hl-attribute">name</span>=<span class="hl-value">"preferences.interests"</span> <span class="hl-attribute">type</span>=<span class="hl-value">"checkbox"</span> <span class="hl-attribute">value</span>=<span class="hl-value">"Herbology"</span>/&gt;
          &lt;<span class="hl-tag">input</span> <span class="hl-attribute">type</span>=<span class="hl-value">"hidden"</span> <span class="hl-attribute">value</span>=<span class="hl-value">"1"</span> <span class="hl-attribute">name</span>=<span class="hl-value">"_preferences.interests"</span>/&gt;
          Defence Against the Dark Arts: &lt;<span class="hl-tag">input</span> <span class="hl-attribute">name</span>=<span class="hl-value">"preferences.interests"</span> <span class="hl-attribute">type</span>=<span class="hl-value">"checkbox"</span>
              <span class="hl-attribute">value</span>=<span class="hl-value">"Defence Against the Dark Arts"</span>/&gt;
          &lt;<span class="hl-tag">input</span> <span class="hl-attribute">type</span>=<span class="hl-value">"hidden"</span> <span class="hl-attribute">value</span>=<span class="hl-value">"1"</span> <span class="hl-attribute">name</span>=<span class="hl-value">"_preferences.interests"</span>/&gt;
      &lt;<span class="hl-tag">/td</span>&gt;
  &lt;<span class="hl-tag">/tr</span>&gt;</pre><p>What you might not expect to see is the additional hidden field
      after each checkbox. When a checkbox in an HTML page is
      <span class="emphasis"><em>not</em></span> checked, its value will not be sent to the
      server as part of the HTTP request parameters once the form is
      submitted, so we need a workaround for this quirk in HTML in order for
      Spring form data binding to work. The <code class="literal">checkbox</code> tag
      follows the existing Spring convention of including a hidden parameter
      prefixed by an underscore ("_") for each checkbox. By doing this, you
      are effectively telling Spring that &#8220;<span class="quote">
          <span class="emphasis"><em>the checkbox was visible in the form and I want my object
          to which the form data will be bound to reflect the state of the
          checkbox no matter what</em></span>
        </span>&#8221;.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="view-jsp-formtaglib-checkboxestag"></a>16.2.4.5&nbsp;The <code class="literal">checkboxes</code> tag</h4></div></div></div><p>This tag renders multiple HTML 'input' tags with type
        'checkbox'.</p><p>Building on the example from the previous
        <code class="classname">checkbox</code> tag section. Sometimes you prefer not
        to have to list all the possible hobbies in your JSP page. You would
        rather provide a list at runtime of the available options and pass
        that in to the tag. That is the purpose of the
        <code class="classname">checkboxes</code> tag. You pass in an
        <code class="classname">Array</code>, a <code class="classname">List</code> or a
        <code class="classname">Map</code> containing the available options in the
        "items" property. Typically the bound property is a collection so it
        can hold multiple values selected by the user. Below is an example of
        the JSP using this tag:</p><pre class="programlisting">&lt;<span class="hl-tag">form:form</span>&gt;
      &lt;<span class="hl-tag">table</span>&gt;
          &lt;<span class="hl-tag">tr</span>&gt;
              &lt;<span class="hl-tag">td</span>&gt;Interests:&lt;<span class="hl-tag">/td</span>&gt;
              &lt;<span class="hl-tag">td</span>&gt;
                  &lt;<span class="hl-tag">%--</span> <span class="hl-attribute">Property</span> <span class="hl-attribute">is</span> <span class="hl-attribute">of</span> <span class="hl-attribute">an</span> <span class="hl-attribute">array</span> <span class="hl-attribute">or</span> <span class="hl-attribute">of</span> <span class="hl-attribute">type</span> <span class="hl-attribute">java.util.Collection</span> <span class="hl-attribute">--%&gt;</span>
                  <span class="hl-attribute">&lt;form:checkboxes</span> <span class="hl-attribute">path</span>=<span class="hl-value">"preferences.interests"</span> <span class="hl-attribute">items</span>=<span class="hl-value">"${interestList}"</span>/&gt;
              &lt;<span class="hl-tag">/td</span>&gt;
          &lt;<span class="hl-tag">/tr</span>&gt;
      &lt;<span class="hl-tag">/table</span>&gt;
  &lt;<span class="hl-tag">/form:form</span>&gt;</pre><p>This example assumes that the "interestList" is a
      <code class="classname">List</code> available as a model attribute containing
      strings of the values to be selected from. In the case where you use a
      Map, the map entry key will be used as the value and the map entry's
      value will be used as the label to be displayed. You can also use a
      custom object where you can provide the property names for the value
      using "itemValue" and the label using "itemLabel".</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="view-jsp-formtaglib-radiobuttontag"></a>16.2.4.6&nbsp;The <code class="literal">radiobutton</code> tag</h4></div></div></div><p>This tag renders an HTML 'input' tag with type 'radio'.</p><p>A typical usage pattern will involve multiple tag instances
        bound to the same property but with different values.</p><pre class="programlisting">&lt;<span class="hl-tag">tr</span>&gt;
      &lt;<span class="hl-tag">td</span>&gt;Sex:&lt;<span class="hl-tag">/td</span>&gt;
      &lt;<span class="hl-tag">td</span>&gt;Male: &lt;<span class="hl-tag">form:radiobutton</span> <span class="hl-attribute">path</span>=<span class="hl-value">"sex"</span> <span class="hl-attribute">value</span>=<span class="hl-value">"M"</span>/&gt; &lt;<span class="hl-tag">br</span>/&gt;
          Female: &lt;<span class="hl-tag">form:radiobutton</span> <span class="hl-attribute">path</span>=<span class="hl-value">"sex"</span> <span class="hl-attribute">value</span>=<span class="hl-value">"F"</span>/&gt; &lt;<span class="hl-tag">/td</span>&gt;
  &lt;<span class="hl-tag">/tr</span>&gt;</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="view-jsp-formtaglib-radiobuttonstag"></a>16.2.4.7&nbsp;The <code class="literal">radiobuttons</code> tag</h4></div></div></div><p>This tag renders multiple HTML 'input' tags with type
        'radio'.</p><p>Just like the <code class="classname">checkboxes</code> tag above, you
        might want to pass in the available options as a runtime variable. For
        this usage you would use the <code class="classname">radiobuttons</code> tag.
        You pass in an <code class="classname">Array</code>, a
        <code class="classname">List</code> or a <code class="classname">Map</code> containing
        the available options in the "items" property. In the case where you
        use a Map, the map entry key will be used as the value and the map
        entry's value will be used as the label to be displayed. You can also
        use a custom object where you can provide the property names for the
        value using "itemValue" and the label using "itemLabel".</p><pre class="programlisting">&lt;<span class="hl-tag">tr</span>&gt;
      &lt;<span class="hl-tag">td</span>&gt;Sex:&lt;<span class="hl-tag">/td</span>&gt;
      &lt;<span class="hl-tag">td</span>&gt;&lt;<span class="hl-tag">form:radiobuttons</span> <span class="hl-attribute">path</span>=<span class="hl-value">"sex"</span> <span class="hl-attribute">items</span>=<span class="hl-value">"${sexOptions}"</span>/&gt;&lt;<span class="hl-tag">/td</span>&gt;
  &lt;<span class="hl-tag">/tr</span>&gt;</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="view-jsp-formtaglib-passwordtag"></a>16.2.4.8&nbsp;The <code class="literal">password</code> tag</h4></div></div></div><p>This tag renders an HTML 'input' tag with type 'password' using
        the bound value.</p><pre class="programlisting">&lt;<span class="hl-tag">tr</span>&gt;
      &lt;<span class="hl-tag">td</span>&gt;Password:&lt;<span class="hl-tag">/td</span>&gt;
      &lt;<span class="hl-tag">td</span>&gt;
          &lt;<span class="hl-tag">form:password</span> <span class="hl-attribute">path</span>=<span class="hl-value">"password"</span> /&gt;
      &lt;<span class="hl-tag">/td</span>&gt;
  &lt;<span class="hl-tag">/tr</span>&gt;</pre><p>Please note that by default, the password value is
        <span class="emphasis"><em>not</em></span> shown. If you do want the password value to
        be shown, then set the value of the <code class="literal">'showPassword'</code>
        attribute to true, like so.</p><pre class="programlisting">&lt;<span class="hl-tag">tr</span>&gt;
      &lt;<span class="hl-tag">td</span>&gt;Password:&lt;<span class="hl-tag">/td</span>&gt;
      &lt;<span class="hl-tag">td</span>&gt;
          &lt;<span class="hl-tag">form:password</span> <span class="hl-attribute">path</span>=<span class="hl-value">"password"</span> <span class="hl-attribute">value</span>=<span class="hl-value">"^76525bvHGq"</span> <span class="hl-attribute">showPassword</span>=<span class="hl-value">"true"</span> /&gt;
      &lt;<span class="hl-tag">/td</span>&gt;
  &lt;<span class="hl-tag">/tr</span>&gt;</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="view-jsp-formtaglib-selecttag"></a>16.2.4.9&nbsp;The <code class="literal">select</code> tag</h4></div></div></div><p>This tag renders an HTML 'select' element. It supports data
        binding to the selected option as well as the use of nested
        <code class="literal">option</code> and <code class="literal">options</code> tags.</p><p>Let's assume a <code class="classname">User</code> has a list of
        skills.</p><pre class="programlisting">&lt;<span class="hl-tag">tr</span>&gt;
      &lt;<span class="hl-tag">td</span>&gt;Skills:&lt;<span class="hl-tag">/td</span>&gt;
      &lt;<span class="hl-tag">td</span>&gt;&lt;<span class="hl-tag">form:select</span> <span class="hl-attribute">path</span>=<span class="hl-value">"skills"</span> <span class="hl-attribute">items</span>=<span class="hl-value">"${skills}"</span>/&gt;&lt;<span class="hl-tag">/td</span>&gt;
  &lt;<span class="hl-tag">/tr</span>&gt;</pre><p>If the <code class="literal">User's</code> skill were in Herbology, the
        HTML source of the 'Skills' row would look like:</p><pre class="programlisting">&lt;<span class="hl-tag">tr</span>&gt;
      &lt;<span class="hl-tag">td</span>&gt;Skills:&lt;<span class="hl-tag">/td</span>&gt;
      &lt;<span class="hl-tag">td</span>&gt;&lt;<span class="hl-tag">select</span> <span class="hl-attribute">name</span>=<span class="hl-value">"skills"</span> <span class="hl-attribute">multiple</span>=<span class="hl-value">"true"</span>&gt;
          &lt;<span class="hl-tag">option</span> <span class="hl-attribute">value</span>=<span class="hl-value">"Potions"</span>&gt;Potions&lt;<span class="hl-tag">/option</span>&gt;
          &lt;<span class="hl-tag">option</span> <span class="hl-attribute">value</span>=<span class="hl-value">"Herbology"</span> <span class="hl-attribute">selected</span>=<span class="hl-value">"selected"</span>&gt;Herbology&lt;<span class="hl-tag">/option</span>&gt;
          &lt;<span class="hl-tag">option</span> <span class="hl-attribute">value</span>=<span class="hl-value">"Quidditch"</span>&gt;Quidditch&lt;<span class="hl-tag">/option</span>&gt;&lt;<span class="hl-tag">/select</span>&gt;
      &lt;<span class="hl-tag">/td</span>&gt;
  &lt;<span class="hl-tag">/tr</span>&gt;</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="view-jsp-formtaglib-optiontag"></a>16.2.4.10&nbsp;The <code class="literal">option</code> tag</h4></div></div></div><p>This tag renders an HTML 'option'. It sets 'selected' as
        appropriate based on the bound value.</p><pre class="programlisting">&lt;<span class="hl-tag">tr</span>&gt;
      &lt;<span class="hl-tag">td</span>&gt;House:&lt;<span class="hl-tag">/td</span>&gt;
      &lt;<span class="hl-tag">td</span>&gt;
          &lt;<span class="hl-tag">form:select</span> <span class="hl-attribute">path</span>=<span class="hl-value">"house"</span>&gt;
              &lt;<span class="hl-tag">form:option</span> <span class="hl-attribute">value</span>=<span class="hl-value">"Gryffindor"</span>/&gt;
              &lt;<span class="hl-tag">form:option</span> <span class="hl-attribute">value</span>=<span class="hl-value">"Hufflepuff"</span>/&gt;
              &lt;<span class="hl-tag">form:option</span> <span class="hl-attribute">value</span>=<span class="hl-value">"Ravenclaw"</span>/&gt;
              &lt;<span class="hl-tag">form:option</span> <span class="hl-attribute">value</span>=<span class="hl-value">"Slytherin"</span>/&gt;
          &lt;<span class="hl-tag">/form:select</span>&gt;
      &lt;<span class="hl-tag">/td</span>&gt;
  &lt;<span class="hl-tag">/tr</span>&gt;</pre><p>If the <code class="literal">User's</code> house was in Gryffindor, the
        HTML source of the 'House' row would look like:</p><pre class="programlisting">&lt;<span class="hl-tag">tr</span>&gt;
      &lt;<span class="hl-tag">td</span>&gt;House:&lt;<span class="hl-tag">/td</span>&gt;
      &lt;<span class="hl-tag">td</span>&gt;
          &lt;<span class="hl-tag">select</span> <span class="hl-attribute">name</span>=<span class="hl-value">"house"</span>&gt;
              &lt;<span class="hl-tag">option</span> <span class="hl-attribute">value</span>=<span class="hl-value">"Gryffindor"</span> <span class="hl-attribute">selected</span>=<span class="hl-value">"selected"</span>&gt;Gryffindor&lt;<span class="hl-tag">/option</span>&gt;
              &lt;<span class="hl-tag">option</span> <span class="hl-attribute">value</span>=<span class="hl-value">"Hufflepuff"</span>&gt;Hufflepuff&lt;<span class="hl-tag">/option</span>&gt;
              &lt;<span class="hl-tag">option</span> <span class="hl-attribute">value</span>=<span class="hl-value">"Ravenclaw"</span>&gt;Ravenclaw&lt;<span class="hl-tag">/option</span>&gt;
              &lt;<span class="hl-tag">option</span> <span class="hl-attribute">value</span>=<span class="hl-value">"Slytherin"</span>&gt;Slytherin&lt;<span class="hl-tag">/option</span>&gt;
          &lt;<span class="hl-tag">/select</span>&gt;
      &lt;<span class="hl-tag">/td</span>&gt;
   &lt;<span class="hl-tag">/tr</span>&gt;</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="view-jsp-formtaglib-optionstag"></a>16.2.4.11&nbsp;The <code class="literal">options</code> tag</h4></div></div></div><p>This tag renders a list of HTML 'option' tags. It sets the
        'selected' attribute as appropriate based on the bound value.</p><pre class="programlisting">&lt;<span class="hl-tag">tr</span>&gt;
      &lt;<span class="hl-tag">td</span>&gt;Country:&lt;<span class="hl-tag">/td</span>&gt;
      &lt;<span class="hl-tag">td</span>&gt;
          &lt;<span class="hl-tag">form:select</span> <span class="hl-attribute">path</span>=<span class="hl-value">"country"</span>&gt;
              &lt;<span class="hl-tag">form:option</span> <span class="hl-attribute">value</span>=<span class="hl-value">"-"</span> <span class="hl-attribute">label</span>=<span class="hl-value">"--Please Select"</span>/&gt;
              &lt;<span class="hl-tag">form:options</span> <span class="hl-attribute">items</span>=<span class="hl-value">"${countryList}"</span> <span class="hl-attribute">itemValue</span>=<span class="hl-value">"code"</span> <span class="hl-attribute">itemLabel</span>=<span class="hl-value">"name"</span>/&gt;
          &lt;<span class="hl-tag">/form:select</span>&gt;
      &lt;<span class="hl-tag">/td</span>&gt;
  &lt;<span class="hl-tag">/tr</span>&gt;</pre><p>If the <code class="classname">User</code> lived in the UK, the HTML
        source of the 'Country' row would look like:</p><pre class="programlisting">&lt;<span class="hl-tag">tr</span>&gt;
      &lt;<span class="hl-tag">td</span>&gt;Country:&lt;<span class="hl-tag">/td</span>&gt;
      &lt;<span class="hl-tag">td</span>&gt;
          &lt;<span class="hl-tag">select</span> <span class="hl-attribute">name</span>=<span class="hl-value">"country"</span>&gt;
              &lt;<span class="hl-tag">option</span> <span class="hl-attribute">value</span>=<span class="hl-value">"-"</span>&gt;--Please Select&lt;<span class="hl-tag">/option</span>&gt;
              &lt;<span class="hl-tag">option</span> <span class="hl-attribute">value</span>=<span class="hl-value">"AT"</span>&gt;Austria&lt;<span class="hl-tag">/option</span>&gt;
              &lt;<span class="hl-tag">option</span> <span class="hl-attribute">value</span>=<span class="hl-value">"UK"</span> <span class="hl-attribute">selected</span>=<span class="hl-value">"selected"</span>&gt;United Kingdom&lt;<span class="hl-tag">/option</span>&gt;
              &lt;<span class="hl-tag">option</span> <span class="hl-attribute">value</span>=<span class="hl-value">"US"</span>&gt;United States&lt;<span class="hl-tag">/option</span>&gt;
          &lt;<span class="hl-tag">/select</span>&gt;
      &lt;<span class="hl-tag">/td</span>&gt;
  &lt;<span class="hl-tag">/tr</span>&gt;</pre><p>As the example shows, the combined usage of an
        <code class="literal">option</code> tag with the <code class="literal">options</code> tag
        generates the same standard HTML, but allows you to explicitly specify
        a value in the JSP that is for display only (where it belongs) such as
        the default string in the example: "-- Please Select".</p><p>The <code class="literal">items</code> attribute is typically populated
        with a collection or array of item objects.
        <code class="literal">itemValue</code> and <code class="literal">itemLabel</code> simply
        refer to bean properties of those item objects, if specified;
        otherwise, the item objects themselves will be stringified.
        Alternatively, you may specify a <code class="literal">Map</code> of items, in
        which case the map keys are interpreted as option values and the map
        values correspond to option labels. If <code class="literal">itemValue</code>
        and/or <code class="literal">itemLabel</code> happen to be specified as well,
        the item value property will apply to the map key and the item label
        property will apply to the map value.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="view-jsp-formtaglib-textAreatag"></a>16.2.4.12&nbsp;The <code class="literal">textarea</code> tag</h4></div></div></div><p>This tag renders an HTML 'textarea'.</p><pre class="programlisting">&lt;<span class="hl-tag">tr</span>&gt;
      &lt;<span class="hl-tag">td</span>&gt;Notes:&lt;<span class="hl-tag">/td</span>&gt;
      &lt;<span class="hl-tag">td</span>&gt;&lt;<span class="hl-tag">form:textarea</span> <span class="hl-attribute">path</span>=<span class="hl-value">"notes"</span> <span class="hl-attribute">rows</span>=<span class="hl-value">"3"</span> <span class="hl-attribute">cols</span>=<span class="hl-value">"20"</span> /&gt;&lt;<span class="hl-tag">/td</span>&gt;
      &lt;<span class="hl-tag">td</span>&gt;&lt;<span class="hl-tag">form:errors</span> <span class="hl-attribute">path</span>=<span class="hl-value">"notes"</span> /&gt;&lt;<span class="hl-tag">/td</span>&gt;
  &lt;<span class="hl-tag">/tr</span>&gt;</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="view-jsp-formtaglib-hiddeninputtag"></a>16.2.4.13&nbsp;The <code class="literal">hidden</code> tag</h4></div></div></div><p>This tag renders an HTML 'input' tag with type 'hidden' using
        the bound value. To submit an unbound hidden value, use the HTML
        <code class="literal">input</code> tag with type 'hidden'.</p><pre class="programlisting">&lt;<span class="hl-tag">form:hidden</span> <span class="hl-attribute">path</span>=<span class="hl-value">"house"</span> /&gt;
  </pre><p>If we choose to submit the 'house' value as a hidden one, the
        HTML would look like:</p><pre class="programlisting">&lt;<span class="hl-tag">input</span> <span class="hl-attribute">name</span>=<span class="hl-value">"house"</span> <span class="hl-attribute">type</span>=<span class="hl-value">"hidden"</span> <span class="hl-attribute">value</span>=<span class="hl-value">"Gryffindor"</span>/&gt;
  </pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="view-jsp-formtaglib-errorstag"></a>16.2.4.14&nbsp;The <code class="literal">errors</code> tag</h4></div></div></div><p>This tag renders field errors in an HTML 'span' tag. It provides
        access to the errors created in your controller or those that were
        created by any validators associated with your controller.</p><p>Let's assume we want to display all error messages for the
        <code class="literal">firstName</code> and <code class="literal">lastName</code> fields
        once we submit the form. We have a validator for instances of the
        <code class="classname">User</code> class called
        <code class="classname">UserValidator</code>.</p><pre class="programlisting"><span class="hl-keyword">public</span> <span class="hl-keyword">class</span> UserValidator <span class="hl-keyword">implements</span> Validator {

      <span class="hl-keyword">public</span> <span class="hl-keyword">boolean</span> supports(Class candidate) {
          <span class="hl-keyword">return</span> User.<span class="hl-keyword">class</span>.isAssignableFrom(candidate);
      }

      <span class="hl-keyword">public</span> <span class="hl-keyword">void</span> validate(Object obj, Errors errors) {
          ValidationUtils.rejectIfEmptyOrWhitespace(errors, <span class="hl-string">"firstName"</span>, <span class="hl-string">"required"</span>, <span class="hl-string">"Field is required."</span>);
          ValidationUtils.rejectIfEmptyOrWhitespace(errors, <span class="hl-string">"lastName"</span>, <span class="hl-string">"required"</span>, <span class="hl-string">"Field is required."</span>);
      }
  }</pre><p>The <code class="literal">form.jsp</code> would look like:</p><pre class="programlisting">&lt;<span class="hl-tag">form:form</span>&gt;
      &lt;<span class="hl-tag">table</span>&gt;
          &lt;<span class="hl-tag">tr</span>&gt;
              &lt;<span class="hl-tag">td</span>&gt;First Name:&lt;<span class="hl-tag">/td</span>&gt;
              &lt;<span class="hl-tag">td</span>&gt;&lt;<span class="hl-tag">form:input</span> <span class="hl-attribute">path</span>=<span class="hl-value">"firstName"</span> /&gt;&lt;<span class="hl-tag">/td</span>&gt;
              &lt;<span class="hl-tag">%--</span> <span class="hl-attribute">Show</span> <span class="hl-attribute">errors</span> <span class="hl-attribute">for</span> <span class="hl-attribute">firstName</span> <span class="hl-attribute">field</span> <span class="hl-attribute">--%&gt;</span>
              <span class="hl-attribute">&lt;td&gt;&lt;form:errors</span> <span class="hl-attribute">path</span>=<span class="hl-value">"firstName"</span> /&gt;&lt;<span class="hl-tag">/td</span>&gt;
          &lt;<span class="hl-tag">/tr</span>&gt;

          &lt;<span class="hl-tag">tr</span>&gt;
              &lt;<span class="hl-tag">td</span>&gt;Last Name:&lt;<span class="hl-tag">/td</span>&gt;
              &lt;<span class="hl-tag">td</span>&gt;&lt;<span class="hl-tag">form:input</span> <span class="hl-attribute">path</span>=<span class="hl-value">"lastName"</span> /&gt;&lt;<span class="hl-tag">/td</span>&gt;
              &lt;<span class="hl-tag">%--</span> <span class="hl-attribute">Show</span> <span class="hl-attribute">errors</span> <span class="hl-attribute">for</span> <span class="hl-attribute">lastName</span> <span class="hl-attribute">field</span> <span class="hl-attribute">--%&gt;</span>
              <span class="hl-attribute">&lt;td&gt;&lt;form:errors</span> <span class="hl-attribute">path</span>=<span class="hl-value">"lastName"</span>  /&gt;&lt;<span class="hl-tag">/td</span>&gt;
          &lt;<span class="hl-tag">/tr</span>&gt;
          &lt;<span class="hl-tag">tr</span>&gt;
              &lt;<span class="hl-tag">td</span> <span class="hl-attribute">colspan</span>=<span class="hl-value">"3"</span>&gt;
                  &lt;<span class="hl-tag">input</span> <span class="hl-attribute">type</span>=<span class="hl-value">"submit"</span> <span class="hl-attribute">value</span>=<span class="hl-value">"Save Changes"</span> /&gt;
              &lt;<span class="hl-tag">/td</span>&gt;
          &lt;<span class="hl-tag">/tr</span>&gt;
      &lt;<span class="hl-tag">/table</span>&gt;
  &lt;<span class="hl-tag">/form:form</span>&gt;</pre><p>If we submit a form with empty values in the
        <code class="literal">firstName</code> and <code class="literal">lastName</code> fields,
        this is what the HTML would look like:</p><pre class="programlisting">&lt;<span class="hl-tag">form</span> <span class="hl-attribute">method</span>=<span class="hl-value">"POST"</span>&gt;
      &lt;<span class="hl-tag">table</span>&gt;
          &lt;<span class="hl-tag">tr</span>&gt;
              &lt;<span class="hl-tag">td</span>&gt;First Name:&lt;<span class="hl-tag">/td</span>&gt;
              &lt;<span class="hl-tag">td</span>&gt;&lt;<span class="hl-tag">input</span> <span class="hl-attribute">name</span>=<span class="hl-value">"firstName"</span> <span class="hl-attribute">type</span>=<span class="hl-value">"text"</span> <span class="hl-attribute">value</span>=<span class="hl-value">""</span>/&gt;&lt;<span class="hl-tag">/td</span>&gt;
              &lt;<span class="hl-tag">%--</span> <span class="hl-attribute">Associated</span> <span class="hl-attribute">errors</span> <span class="hl-attribute">to</span> <span class="hl-attribute">firstName</span> <span class="hl-attribute">field</span> <span class="hl-attribute">displayed</span> <span class="hl-attribute">--%&gt;</span>
              <span class="hl-attribute">&lt;td&gt;&lt;span</span> <span class="hl-attribute">name</span>=<span class="hl-value">"firstName.errors"</span>&gt;Field is required.&lt;<span class="hl-tag">/span</span>&gt;&lt;<span class="hl-tag">/td</span>&gt;
          &lt;<span class="hl-tag">/tr</span>&gt;

          &lt;<span class="hl-tag">tr</span>&gt;
              &lt;<span class="hl-tag">td</span>&gt;Last Name:&lt;<span class="hl-tag">/td</span>&gt;
              &lt;<span class="hl-tag">td</span>&gt;&lt;<span class="hl-tag">input</span> <span class="hl-attribute">name</span>=<span class="hl-value">"lastName"</span> <span class="hl-attribute">type</span>=<span class="hl-value">"text"</span> <span class="hl-attribute">value</span>=<span class="hl-value">""</span>/&gt;&lt;<span class="hl-tag">/td</span>&gt;
              &lt;<span class="hl-tag">%--</span> <span class="hl-attribute">Associated</span> <span class="hl-attribute">errors</span> <span class="hl-attribute">to</span> <span class="hl-attribute">lastName</span> <span class="hl-attribute">field</span> <span class="hl-attribute">displayed</span> <span class="hl-attribute">--%&gt;</span>
              <span class="hl-attribute">&lt;td&gt;&lt;span</span> <span class="hl-attribute">name</span>=<span class="hl-value">"lastName.errors"</span>&gt;Field is required.&lt;<span class="hl-tag">/span</span>&gt;&lt;<span class="hl-tag">/td</span>&gt;
          &lt;<span class="hl-tag">/tr</span>&gt;
          &lt;<span class="hl-tag">tr</span>&gt;
              &lt;<span class="hl-tag">td</span> <span class="hl-attribute">colspan</span>=<span class="hl-value">"3"</span>&gt;
                  &lt;<span class="hl-tag">input</span> <span class="hl-attribute">type</span>=<span class="hl-value">"submit"</span> <span class="hl-attribute">value</span>=<span class="hl-value">"Save Changes"</span> /&gt;
              &lt;<span class="hl-tag">/td</span>&gt;
          &lt;<span class="hl-tag">/tr</span>&gt;
      &lt;<span class="hl-tag">/table</span>&gt;
  &lt;<span class="hl-tag">/form</span>&gt;</pre><p>What if we want to display the entire list of errors for a given
        page? The example below shows that the <code class="literal">errors</code> tag
        also supports some basic wildcarding functionality.</p><div class="itemizedlist"><ul type="disc"><li><p><code class="literal">path="*"</code> - displays all errors</p></li><li><p><code class="literal">path="lastName"</code> - displays all errors
            associated with the <code class="literal">lastName</code> field</p></li></ul></div><p>The example below will display a list of errors at the top of
        the page, followed by field-specific errors next to the fields:</p><pre class="programlisting">&lt;<span class="hl-tag">form:form</span>&gt;
      &lt;<span class="hl-tag">form:errors</span> <span class="hl-attribute">path</span>=<span class="hl-value">"*"</span> <span class="hl-attribute">cssClass</span>=<span class="hl-value">"errorBox"</span> /&gt;
      &lt;<span class="hl-tag">table</span>&gt;
          &lt;<span class="hl-tag">tr</span>&gt;
              &lt;<span class="hl-tag">td</span>&gt;First Name:&lt;<span class="hl-tag">/td</span>&gt;
              &lt;<span class="hl-tag">td</span>&gt;&lt;<span class="hl-tag">form:input</span> <span class="hl-attribute">path</span>=<span class="hl-value">"firstName"</span> /&gt;&lt;<span class="hl-tag">/td</span>&gt;
              &lt;<span class="hl-tag">td</span>&gt;&lt;<span class="hl-tag">form:errors</span> <span class="hl-attribute">path</span>=<span class="hl-value">"firstName"</span> /&gt;&lt;<span class="hl-tag">/td</span>&gt;
          &lt;<span class="hl-tag">/tr</span>&gt;
          &lt;<span class="hl-tag">tr</span>&gt;
              &lt;<span class="hl-tag">td</span>&gt;Last Name:&lt;<span class="hl-tag">/td</span>&gt;
              &lt;<span class="hl-tag">td</span>&gt;&lt;<span class="hl-tag">form:input</span> <span class="hl-attribute">path</span>=<span class="hl-value">"lastName"</span> /&gt;&lt;<span class="hl-tag">/td</span>&gt;
              &lt;<span class="hl-tag">td</span>&gt;&lt;<span class="hl-tag">form:errors</span> <span class="hl-attribute">path</span>=<span class="hl-value">"lastName"</span>  /&gt;&lt;<span class="hl-tag">/td</span>&gt;
          &lt;<span class="hl-tag">/tr</span>&gt;
          &lt;<span class="hl-tag">tr</span>&gt;
              &lt;<span class="hl-tag">td</span> <span class="hl-attribute">colspan</span>=<span class="hl-value">"3"</span>&gt;
                  &lt;<span class="hl-tag">input</span> <span class="hl-attribute">type</span>=<span class="hl-value">"submit"</span> <span class="hl-attribute">value</span>=<span class="hl-value">"Save Changes"</span> /&gt;
              &lt;<span class="hl-tag">/td</span>&gt;
          &lt;<span class="hl-tag">/tr</span>&gt;
      &lt;<span class="hl-tag">/table</span>&gt;
  &lt;<span class="hl-tag">/form:form</span>&gt;</pre><p>The HTML would look like:</p><pre class="programlisting">&lt;<span class="hl-tag">form</span> <span class="hl-attribute">method</span>=<span class="hl-value">"POST"</span>&gt;
      &lt;<span class="hl-tag">span</span> <span class="hl-attribute">name</span>=<span class="hl-value">"*.errors"</span> <span class="hl-attribute">class</span>=<span class="hl-value">"errorBox"</span>&gt;Field is required.&lt;<span class="hl-tag">br</span>/&gt;Field is required.&lt;<span class="hl-tag">/span</span>&gt;
      &lt;<span class="hl-tag">table</span>&gt;
          &lt;<span class="hl-tag">tr</span>&gt;
              &lt;<span class="hl-tag">td</span>&gt;First Name:&lt;<span class="hl-tag">/td</span>&gt;
              &lt;<span class="hl-tag">td</span>&gt;&lt;<span class="hl-tag">input</span> <span class="hl-attribute">name</span>=<span class="hl-value">"firstName"</span> <span class="hl-attribute">type</span>=<span class="hl-value">"text"</span> <span class="hl-attribute">value</span>=<span class="hl-value">""</span>/&gt;&lt;<span class="hl-tag">/td</span>&gt;
              &lt;<span class="hl-tag">td</span>&gt;&lt;<span class="hl-tag">span</span> <span class="hl-attribute">name</span>=<span class="hl-value">"firstName.errors"</span>&gt;Field is required.&lt;<span class="hl-tag">/span</span>&gt;&lt;<span class="hl-tag">/td</span>&gt;
          &lt;<span class="hl-tag">/tr</span>&gt;

          &lt;<span class="hl-tag">tr</span>&gt;
              &lt;<span class="hl-tag">td</span>&gt;Last Name:&lt;<span class="hl-tag">/td</span>&gt;
              &lt;<span class="hl-tag">td</span>&gt;&lt;<span class="hl-tag">input</span> <span class="hl-attribute">name</span>=<span class="hl-value">"lastName"</span> <span class="hl-attribute">type</span>=<span class="hl-value">"text"</span> <span class="hl-attribute">value</span>=<span class="hl-value">""</span>/&gt;&lt;<span class="hl-tag">/td</span>&gt;
              &lt;<span class="hl-tag">td</span>&gt;&lt;<span class="hl-tag">span</span> <span class="hl-attribute">name</span>=<span class="hl-value">"lastName.errors"</span>&gt;Field is required.&lt;<span class="hl-tag">/span</span>&gt;&lt;<span class="hl-tag">/td</span>&gt;
          &lt;<span class="hl-tag">/tr</span>&gt;
          &lt;<span class="hl-tag">tr</span>&gt;
              &lt;<span class="hl-tag">td</span> <span class="hl-attribute">colspan</span>=<span class="hl-value">"3"</span>&gt;
                  &lt;<span class="hl-tag">input</span> <span class="hl-attribute">type</span>=<span class="hl-value">"submit"</span> <span class="hl-attribute">value</span>=<span class="hl-value">"Save Changes"</span> /&gt;
              &lt;<span class="hl-tag">/td</span>&gt;
          &lt;<span class="hl-tag">/tr</span>&gt;
  &lt;<span class="hl-tag">/form</span>&gt;</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="rest-method-conversion"></a>16.2.4.15&nbsp;HTTP Method Conversion</h4></div></div></div><p>A key principle of REST is the use of the Uniform Interface.
        This means that all resources (URLs) can be manipulated using the same
        four HTTP methods: GET, PUT, POST, and DELETE. For each method, the
        HTTP specification defines the exact semantics. For instance, a GET
        should always be a safe operation, meaning that is has no side
        effects, and a PUT or DELETE should be idempotent, meaning that you
        can repeat these operations over and over again, but the end result
        should be the same. While HTTP defines these four methods, HTML only
        supports two: GET and POST. Fortunately, there are two possible
        workarounds: you can either use JavaScript to do your PUT or DELETE,
        or simply do a POST with the 'real' method as an additional parameter
        (modeled as a hidden input field in an HTML form). This latter trick
        is what Spring's <code class="classname">HiddenHttpMethodFilter</code> does.
        This filter is a plain Servlet Filter and therefore it can be used in
        combination with any web framework (not just Spring MVC). Simply add
        this filter to your web.xml, and a POST with a hidden _method
        parameter will be converted into the corresponding HTTP method
        request.</p><p>To support HTTP method conversion the Spring MVC form tag was
        updated to support setting the HTTP method. For example, the following
        snippet taken from the updated Petclinic sample</p><pre class="programlisting">&lt;<span class="hl-tag">form:form</span> <span class="hl-attribute">method</span>=<span class="hl-value">"delete"</span>&gt;
      &lt;<span class="hl-tag">p</span> <span class="hl-attribute">class</span>=<span class="hl-value">"submit"</span>&gt;&lt;<span class="hl-tag">input</span> <span class="hl-attribute">type</span>=<span class="hl-value">"submit"</span> <span class="hl-attribute">value</span>=<span class="hl-value">"Delete Pet"</span>/&gt;&lt;<span class="hl-tag">/p</span>&gt;
&lt;<span class="hl-tag">/form:form</span>&gt;</pre><p>This will actually perform an HTTP POST, with the 'real' DELETE
        method hidden behind a request parameter, to be picked up by the
        <code class="classname">HiddenHttpMethodFilter</code>, as defined in web.xml:</p><pre class="programlisting">&lt;filter&gt;
    &lt;filter-name&gt;httpMethodFilter&lt;/filter-name&gt;
    &lt;filter-<span class="hl-keyword">class</span>&gt;org.springframework.web.filter.HiddenHttpMethodFilter&lt;/filter-<span class="hl-keyword">class</span>&gt;
&lt;/filter&gt;

&lt;filter-mapping&gt;
    &lt;filter-name&gt;httpMethodFilter&lt;/filter-name&gt;
    &lt;servlet-name&gt;petclinic&lt;/servlet-name&gt;
&lt;/filter-mapping&gt;</pre><p>The corresponding @Controller method
        is shown below:</p><pre class="programlisting">@RequestMapping(method = RequestMethod.DELETE)
<span class="hl-keyword">public</span> String deletePet(@PathVariable <span class="hl-keyword">int</span> ownerId, @PathVariable <span class="hl-keyword">int</span> petId) {
  <span class="hl-keyword">this</span>.clinic.deletePet(petId);
  <span class="hl-keyword">return</span> <span class="hl-string">"redirect:/owners/"</span> + ownerId;
}</pre></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="view-tiles"></a>16.3&nbsp;Tiles</h2></div></div></div><p>It is possible to integrate Tiles - just as any other view
    technology - in web applications using Spring. The following describes in
    a broad way how to do this.</p><p><span class="emphasis"><em>NOTE:</em></span> This section focuses on Spring's support
    for Tiles 2 (the standalone version of Tiles, requiring Java 5+) in the
    <code class="literal">org.springframework.web.servlet.view.tiles2</code> package.
    Spring also continues to support Tiles 1.x (a.k.a. "Struts Tiles", as
    shipped with Struts 1.1+; compatible with Java 1.4) in the original
    <code class="literal">org.springframework.web.servlet.view.tiles</code>
    package.</p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="view-tiles-dependencies"></a>16.3.1&nbsp;Dependencies</h3></div></div></div><p>To be able to use Tiles you have to have a couple of additional
      dependencies included in your project. The following is the list of
      dependencies you need.</p><div class="itemizedlist"><ul type="disc" compact><li><p><code class="literal">Tiles version 2.1.2 or higher</code></p></li><li><p><code class="literal">Commons BeanUtils</code></p></li><li><p><code class="literal">Commons Digester</code></p></li><li><p><code class="literal">Commons Logging</code></p></li></ul></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="view-tiles-integrate"></a>16.3.2&nbsp;How to integrate Tiles</h3></div></div></div><p>To be able to use Tiles, you have to configure it using files
      containing definitions (for basic information on definitions and other
      Tiles concepts, please have a look at <a class="ulink" href="http://tiles.apache.org" target="_top">http://tiles.apache.org</a>). In Spring this is done using the
      <code class="classname">TilesConfigurer</code>. Have a look at the following
      piece of example ApplicationContext configuration:</p><pre class="programlisting">&lt;<span class="hl-tag">bean</span> <span class="hl-attribute">id</span>=<span class="hl-value">"tilesConfigurer"</span> <span class="hl-attribute">class</span>=<span class="hl-value">"org.springframework.web.servlet.view.tiles2.TilesConfigurer"</span>&gt;
  &lt;<span class="hl-tag">property</span> <span class="hl-attribute">name</span>=<span class="hl-value">"definitions"</span>&gt;
    &lt;<span class="hl-tag">list</span>&gt;
      &lt;<span class="hl-tag">value</span>&gt;/WEB-INF/defs/general.xml&lt;<span class="hl-tag">/value</span>&gt;
      &lt;<span class="hl-tag">value</span>&gt;/WEB-INF/defs/widgets.xml&lt;<span class="hl-tag">/value</span>&gt;
      &lt;<span class="hl-tag">value</span>&gt;/WEB-INF/defs/administrator.xml&lt;<span class="hl-tag">/value</span>&gt;
      &lt;<span class="hl-tag">value</span>&gt;/WEB-INF/defs/customer.xml&lt;<span class="hl-tag">/value</span>&gt;
      &lt;<span class="hl-tag">value</span>&gt;/WEB-INF/defs/templates.xml&lt;<span class="hl-tag">/value</span>&gt;
    &lt;<span class="hl-tag">/list</span>&gt;
  &lt;<span class="hl-tag">/property</span>&gt;
&lt;<span class="hl-tag">/bean</span>&gt;</pre><p>As you can see, there are five files containing definitions, which
      are all located in the <code class="filename">'WEB-INF/defs'</code> directory. At initialization
      of the <code class="interfacename">WebApplicationContext</code>, the files
      will be loaded and the definitions factory will be initialized. After
      that has been done, the Tiles includes in the definition files can be
      used as views within your Spring web application. To be able to use the
      views you have to have a <code class="interfacename">ViewResolver</code>
      just as with any other view technology used with Spring. Below you can
      find two possibilities, the <code class="classname">UrlBasedViewResolver</code>
      and the <code class="classname">ResourceBundleViewResolver</code>.</p><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="view-tiles-url"></a>16.3.2.1&nbsp;
          <code class="classname">UrlBasedViewResolver</code>
        </h4></div></div></div><p>The <code class="classname">UrlBasedViewResolver</code> instantiates the
        given <code class="literal">viewClass</code> for each view it has to
        resolve.</p><pre class="programlisting">&lt;<span class="hl-tag">bean</span> <span class="hl-attribute">id</span>=<span class="hl-value">"viewResolver"</span> <span class="hl-attribute">class</span>=<span class="hl-value">"org.springframework.web.servlet.view.UrlBasedViewResolver"</span>&gt;
  &lt;<span class="hl-tag">property</span> <span class="hl-attribute">name</span>=<span class="hl-value">"viewClass"</span> <span class="hl-attribute">value</span>=<span class="hl-value">"org.springframework.web.servlet.view.tiles2.TilesView"</span>/&gt;
&lt;<span class="hl-tag">/bean</span>&gt;</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="view-tiles-resource"></a>16.3.2.2&nbsp;
          <code class="classname">ResourceBundleViewResolver</code>
        </h4></div></div></div><p>The <code class="classname">ResourceBundleViewResolver</code> has to be
        provided with a property file containing viewnames and viewclasses the
        resolver can use:</p><pre class="programlisting">&lt;<span class="hl-tag">bean</span> <span class="hl-attribute">id</span>=<span class="hl-value">"viewResolver"</span> <span class="hl-attribute">class</span>=<span class="hl-value">"org.springframework.web.servlet.view.ResourceBundleViewResolver"</span>&gt;
  &lt;<span class="hl-tag">property</span> <span class="hl-attribute">name</span>=<span class="hl-value">"basename"</span> <span class="hl-attribute">value</span>=<span class="hl-value">"views"</span>/&gt;
&lt;<span class="hl-tag">/bean</span>&gt;</pre><pre class="programlisting">...
welcomeView.(<span class="hl-keyword">class</span>)=org.springframework.web.servlet.view.tiles2.TilesView
welcomeView.url=welcome (<span class="hl-keyword">this</span> is the name of a Tiles definition)

vetsView.(<span class="hl-keyword">class</span>)=org.springframework.web.servlet.view.tiles2.TilesView
vetsView.url=vetsView (again, <span class="hl-keyword">this</span> is the name of a Tiles definition)

findOwnersForm.(<span class="hl-keyword">class</span>)=org.springframework.web.servlet.view.JstlView
findOwnersForm.url=/WEB-INF/jsp/findOwners.jsp
...</pre><p>As you can see, when using the
        <code class="classname">ResourceBundleViewResolver</code>, you can easily mix
        different view technologies.</p><p>Note that the <code class="classname">TilesView</code> class for Tiles 2
	      supports JSTL (the JSP Standard Tag Library) out of the box, whereas
	      there is a separate <code class="classname">TilesJstlView</code> subclass in the
	      Tiles 1.x support.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="view-tiles-preparer"></a>16.3.2.3&nbsp;<code class="classname">SimpleSpringPreparerFactory</code> and
        <code class="classname">SpringBeanPreparerFactory</code></h4></div></div></div><p>As an advanced feature, Spring also supports two special Tiles 2
        <code class="interfacename">PreparerFactory</code> implementations. Check
        out the Tiles documentation for details on how to use
        <code class="interfacename">ViewPreparer</code> references in your Tiles
        definition files.</p><p>Specify <code class="classname">SimpleSpringPreparerFactory</code> to
        autowire ViewPreparer instances based on specified preparer classes,
        applying Spring's container callbacks as well as applying configured
        Spring BeanPostProcessors. If Spring's context-wide annotation-config
        has been activated, annotations in ViewPreparer classes will be
        automatically detected and applied. Note that this expects preparer
        <span class="emphasis"><em>classes</em></span> in the Tiles definition files, just like
        the default <code class="classname">PreparerFactory</code> does.</p><p>Specify <code class="classname">SpringBeanPreparerFactory</code> to
        operate on specified preparer <span class="emphasis"><em>names</em></span> instead of
        classes, obtaining the corresponding Spring bean from the
        DispatcherServlet's application context. The full bean creation
        process will be in the control of the Spring application context in
        this case, allowing for the use of explicit dependency injection
        configuration, scoped beans etc. Note that you need to define one
        Spring bean definition per preparer name (as used in your Tiles
        definitions).</p><pre class="programlisting">&lt;<span class="hl-tag">bean</span> <span class="hl-attribute">id</span>=<span class="hl-value">"tilesConfigurer"</span> <span class="hl-attribute">class</span>=<span class="hl-value">"org.springframework.web.servlet.view.tiles2.TilesConfigurer"</span>&gt;
  &lt;<span class="hl-tag">property</span> <span class="hl-attribute">name</span>=<span class="hl-value">"definitions"</span>&gt;
    &lt;<span class="hl-tag">list</span>&gt;
      &lt;<span class="hl-tag">value</span>&gt;/WEB-INF/defs/general.xml&lt;<span class="hl-tag">/value</span>&gt;
      &lt;<span class="hl-tag">value</span>&gt;/WEB-INF/defs/widgets.xml&lt;<span class="hl-tag">/value</span>&gt;
      &lt;<span class="hl-tag">value</span>&gt;/WEB-INF/defs/administrator.xml&lt;<span class="hl-tag">/value</span>&gt;
      &lt;<span class="hl-tag">value</span>&gt;/WEB-INF/defs/customer.xml&lt;<span class="hl-tag">/value</span>&gt;
      &lt;<span class="hl-tag">value</span>&gt;/WEB-INF/defs/templates.xml&lt;<span class="hl-tag">/value</span>&gt;
    &lt;<span class="hl-tag">/list</span>&gt;
  &lt;<span class="hl-tag">/property</span>&gt;

  &lt;<span class="hl-comment">!-- resolving preparer names as Spring bean definition names --</span>&gt;
  &lt;<span class="hl-tag">property</span> <span class="hl-attribute">name</span>=<span class="hl-value">"preparerFactoryClass"</span>
       <span class="hl-attribute">value</span>=<span class="hl-value">"org.springframework.web.servlet.view.tiles2.SpringBeanPreparerFactory"</span>/&gt;

&lt;<span class="hl-tag">/bean</span>&gt;</pre></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="view-velocity"></a>16.4&nbsp;Velocity &amp; FreeMarker</h2></div></div></div><p><a class="ulink" href="http://velocity.apache.org" target="_top">Velocity</a> and <a class="ulink" href="http://www.freemarker.org" target="_top">FreeMarker</a> are two templating
    languages that can be used as view technologies within Spring MVC
    applications. The languages are quite similar and serve similar needs and
    so are considered together in this section. For semantic and syntactic
    differences between the two languages, see the <a class="ulink" href="http://www.freemarker.org" target="_top">FreeMarker</a> web site.</p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="view-velocity-dependencies"></a>16.4.1&nbsp;Dependencies</h3></div></div></div><p>Your web application will need to include <code class="filename">velocity-1.x.x.jar</code> or <code class="filename">freemarker-2.x.jar</code> in order to work with
      Velocity or FreeMarker respectively and <code class="filename">commons-collections.jar</code> is required for
      Velocity. Typically they are included in the
      <code class="literal">WEB-INF/lib</code> folder where they are guaranteed to be
      found by a Java EE server and added to the classpath for your application.
      It is of course assumed that you already have the <code class="filename">spring-webmvc.jar</code> in your <code class="filename">'WEB-INF/lib'</code> directory too! If you make use of
      Spring's 'dateToolAttribute' or 'numberToolAttribute' in your Velocity
      views, you will also need to include the <code class="filename">velocity-tools-generic-1.x.jar</code></p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="view-velocity-contextconfig"></a>16.4.2&nbsp;Context configuration</h3></div></div></div><p>A suitable configuration is initialized by adding the relevant
      configurer bean definition to your <code class="filename">'*-servlet.xml'</code>
      as shown below:</p><pre class="programlisting">&lt;<span class="hl-comment">!-- 
  This bean sets up the Velocity environment for us based on a root path for templates.
  Optionally, a properties file can be specified for more control over the Velocity
  environment, but the defaults are pretty sane for file based template loading.
--</span>&gt;
&lt;<span class="hl-tag">bean</span> <span class="hl-attribute">id</span>=<span class="hl-value">"velocityConfig"</span> <span class="hl-attribute">class</span>=<span class="hl-value">"org.springframework.web.servlet.view.velocity.VelocityConfigurer"</span>&gt;
  &lt;<span class="hl-tag">property</span> <span class="hl-attribute">name</span>=<span class="hl-value">"resourceLoaderPath"</span> <span class="hl-attribute">value</span>=<span class="hl-value">"/WEB-INF/velocity/"</span>/&gt;
&lt;<span class="hl-tag">/bean</span>&gt;

&lt;<span class="hl-comment">!-- 

  View resolvers can also be configured with ResourceBundles or XML files. If you need
  different view resolving based on Locale, you have to use the resource bundle resolver.

--</span>&gt;
&lt;<span class="hl-tag">bean</span> <span class="hl-attribute">id</span>=<span class="hl-value">"viewResolver"</span> <span class="hl-attribute">class</span>=<span class="hl-value">"org.springframework.web.servlet.view.velocity.VelocityViewResolver"</span>&gt;
  &lt;<span class="hl-tag">property</span> <span class="hl-attribute">name</span>=<span class="hl-value">"cache"</span> <span class="hl-attribute">value</span>=<span class="hl-value">"true"</span>/&gt;
  &lt;<span class="hl-tag">property</span> <span class="hl-attribute">name</span>=<span class="hl-value">"prefix"</span> <span class="hl-attribute">value</span>=<span class="hl-value">""</span>/&gt;
  &lt;<span class="hl-tag">property</span> <span class="hl-attribute">name</span>=<span class="hl-value">"suffix"</span> <span class="hl-attribute">value</span>=<span class="hl-value">".vm"</span>/&gt;
&lt;<span class="hl-tag">/bean</span>&gt;</pre><pre class="programlisting"><em class="lineannotation"><span class="lineannotation">&lt;!-- freemarker config --&gt;</span></em>
&lt;bean id="freemarkerConfig" class="org.springframework.web.servlet.view.freemarker.FreeMarkerConfigurer"&gt;
  &lt;property name="templateLoaderPath" value="/WEB-INF/freemarker/"/&gt;
&lt;/bean&gt;

<em class="lineannotation"><span class="lineannotation">&lt;!-- 

  View resolvers can also be configured with ResourceBundles or XML files. If you need
  different view resolving based on Locale, you have to use the resource bundle resolver.

--&gt;</span></em>
&lt;bean id="viewResolver" class="org.springframework.web.servlet.view.freemarker.FreeMarkerViewResolver"&gt;
  &lt;property name="cache" value="true"/&gt;
  &lt;property name="prefix" value=""/&gt;
  &lt;property name="suffix" value=".ftl"/&gt;
&lt;/bean&gt;</pre><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.gif"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p>For non web-apps add a
        <code class="classname">VelocityConfigurationFactoryBean</code> or a
        <code class="classname">FreeMarkerConfigurationFactoryBean</code> to your
        application context definition file.</p></td></tr></table></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="view-velocity-createtemplates"></a>16.4.3&nbsp;Creating templates</h3></div></div></div><p>Your templates need to be stored in the directory specified by the
      <code class="literal">*Configurer</code> bean shown above. This document does not
      cover details of creating templates for the two languages - please see
      their relevant websites for information. If you use the view resolvers
      highlighted, then the logical view names relate to the template file
      names in similar fashion to
      <code class="classname">InternalResourceViewResolver</code> for JSP's. So if
      your controller returns a ModelAndView object containing a view name of
      "welcome" then the resolvers will look for the
      <code class="literal">/WEB-INF/freemarker/welcome.ftl</code> or
      <code class="literal">/WEB-INF/velocity/welcome.vm</code> template as
      appropriate.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="view-velocity-advancedconfig"></a>16.4.4&nbsp;Advanced configuration</h3></div></div></div><p>The basic configurations highlighted above will be suitable for
      most application requirements, however additional configuration options
      are available for when unusual or advanced requirements dictate.</p><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="view-velocity-example-velocityproperties"></a>16.4.4.1&nbsp;velocity.properties</h4></div></div></div><p>This file is completely optional, but if specified, contains the
        values that are passed to the Velocity runtime in order to configure
        velocity itself. Only required for advanced configurations, if you
        need this file, specify its location on the
        <code class="literal">VelocityConfigurer</code> bean definition above.</p><pre class="programlisting">&lt;<span class="hl-tag">bean</span> <span class="hl-attribute">id</span>=<span class="hl-value">"velocityConfig"</span> <span class="hl-attribute">class</span>=<span class="hl-value">"org.springframework.web.servlet.view.velocity.VelocityConfigurer"</span>&gt;
  &lt;<span class="hl-tag">property</span> <span class="hl-attribute">name</span>=<span class="hl-value">"configLocation"</span> <span class="hl-attribute">value</span>=<span class="hl-value">"/WEB-INF/velocity.properties"</span>/&gt;
&lt;<span class="hl-tag">/bean</span>&gt;</pre><p>Alternatively, you can specify velocity properties directly in
        the bean definition for the Velocity config bean by replacing the
        "configLocation" property with the following inline properties.</p><pre class="programlisting">&lt;<span class="hl-tag">bean</span> <span class="hl-attribute">id</span>=<span class="hl-value">"velocityConfig"</span> <span class="hl-attribute">class</span>=<span class="hl-value">"org.springframework.web.servlet.view.velocity.VelocityConfigurer"</span>&gt;
  &lt;<span class="hl-tag">property</span> <span class="hl-attribute">name</span>=<span class="hl-value">"velocityProperties"</span>&gt;
    &lt;<span class="hl-tag">props</span>&gt;
      &lt;<span class="hl-tag">prop</span> <span class="hl-attribute">key</span>=<span class="hl-value">"resource.loader"</span>&gt;file&lt;<span class="hl-tag">/prop</span>&gt;
      &lt;<span class="hl-tag">prop</span> <span class="hl-attribute">key</span>=<span class="hl-value">"file.resource.loader.class"</span>&gt;
        org.apache.velocity.runtime.resource.loader.FileResourceLoader
      &lt;<span class="hl-tag">/prop</span>&gt;
      &lt;<span class="hl-tag">prop</span> <span class="hl-attribute">key</span>=<span class="hl-value">"file.resource.loader.path"</span>&gt;${webapp.root}/WEB-INF/velocity&lt;<span class="hl-tag">/prop</span>&gt;
      &lt;<span class="hl-tag">prop</span> <span class="hl-attribute">key</span>=<span class="hl-value">"file.resource.loader.cache"</span>&gt;false&lt;<span class="hl-tag">/prop</span>&gt;
    &lt;<span class="hl-tag">/props</span>&gt;
  &lt;<span class="hl-tag">/property</span>&gt;
&lt;<span class="hl-tag">/bean</span>&gt;</pre><p>Refer to the <a class="ulink" href="http://static.springframework.org/spring/docs/3.0.x/javadoc-api/org/springframework/ui/velocity/VelocityEngineFactory.html" target="_top">API
        documentation</a> for Spring configuration of Velocity, or the
        Velocity documentation for examples and definitions of the
        <code class="filename">'velocity.properties'</code> file itself.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="views-freemarker"></a>16.4.4.2&nbsp;FreeMarker</h4></div></div></div><p>FreeMarker 'Settings' and 'SharedVariables' can be passed
        directly to the FreeMarker <code class="literal">Configuration</code> object
        managed by Spring by setting the appropriate bean properties on the
        <code class="literal">FreeMarkerConfigurer</code> bean. The
        <code class="literal">freemarkerSettings</code> property requires a
        <code class="literal">java.util.Properties</code> object and the
        <code class="literal">freemarkerVariables</code> property requires a
        <code class="literal">java.util.Map</code>.</p><pre class="programlisting">&lt;<span class="hl-tag">bean</span> <span class="hl-attribute">id</span>=<span class="hl-value">"freemarkerConfig"</span> <span class="hl-attribute">class</span>=<span class="hl-value">"org.springframework.web.servlet.view.freemarker.FreeMarkerConfigurer"</span>&gt;
  &lt;<span class="hl-tag">property</span> <span class="hl-attribute">name</span>=<span class="hl-value">"templateLoaderPath"</span> <span class="hl-attribute">value</span>=<span class="hl-value">"/WEB-INF/freemarker/"</span>/&gt;
  &lt;<span class="hl-tag">property</span> <span class="hl-attribute">name</span>=<span class="hl-value">"freemarkerVariables"</span>&gt;
    &lt;<span class="hl-tag">map</span>&gt;
      &lt;<span class="hl-tag">entry</span> <span class="hl-attribute">key</span>=<span class="hl-value">"xml_escape"</span> <span class="hl-attribute">value-ref</span>=<span class="hl-value">"fmXmlEscape"</span>/&gt;
    &lt;<span class="hl-tag">/map</span>&gt;
  &lt;<span class="hl-tag">/property</span>&gt;
&lt;<span class="hl-tag">/bean</span>&gt;

&lt;<span class="hl-tag">bean</span> <span class="hl-attribute">id</span>=<span class="hl-value">"fmXmlEscape"</span> <span class="hl-attribute">class</span>=<span class="hl-value">"freemarker.template.utility.XmlEscape"</span>/&gt;</pre><p>See the FreeMarker documentation for details of settings and
        variables as they apply to the <code class="classname">Configuration</code>
        object.</p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="view-velocity-forms"></a>16.4.5&nbsp;Bind support and form handling</h3></div></div></div><p>Spring provides a tag library for use in JSP's that contains
      (amongst other things) a <code class="literal">&lt;spring:bind/&gt;</code> tag.
      This tag primarily enables forms to display values from form backing
      objects and to show the results of failed validations from a
      <code class="literal">Validator</code> in the web or business tier. From version
      1.1, Spring now has support for the same functionality in both Velocity
      and FreeMarker, with additional convenience macros for generating form
      input elements themselves.</p><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="view-bind-macros"></a>16.4.5.1&nbsp;The bind macros</h4></div></div></div><p>A standard set of macros are maintained within the
        <code class="literal">spring-webmvc.jar</code> file for both languages, so they are
        always available to a suitably configured application.</p><p>Some of the macros defined in the Spring libraries are
        considered internal (private) but no such scoping exists in the macro
        definitions making all macros visible to calling code and user
        templates. The following sections concentrate only on the macros you
        need to be directly calling from within your templates. If you wish to
        view the macro code directly, the files are called spring.vm /
        spring.ftl and are in the packages
        <code class="literal">org.springframework.web.servlet.view.velocity</code> or
        <code class="literal">org.springframework.web.servlet.view.freemarker</code>
        respectively.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="view-simple-binding"></a>16.4.5.2&nbsp;Simple binding</h4></div></div></div><p>In your html forms (vm / ftl templates) that act as the
        'formView' for a Spring form controller, you can use code similar to
        the following to bind to field values and display error messages for
        each input field in similar fashion to the JSP equivalent. Note that
        the name of the command object is "command" by default, but can be
        overridden in your MVC configuration by setting the 'commandName' bean
        property on your form controller. Example code is shown below for the
        <code class="literal">personFormV</code> and <code class="literal">personFormF</code>
        views configured earlier;</p><pre class="programlisting">&lt;<span class="hl-comment">!-- velocity macros are automatically available --</span>&gt;
&lt;<span class="hl-tag">html</span>&gt;
...
&lt;<span class="hl-tag">form</span> <span class="hl-attribute">action</span>=<span class="hl-value">""</span> <span class="hl-attribute">method</span>=<span class="hl-value">"POST"</span>&gt;
  Name: 
  #springBind( "command.name" )
  &lt;<span class="hl-tag">input</span> <span class="hl-attribute">type</span>=<span class="hl-value">"text"</span> 
    <span class="hl-attribute">name</span>=<span class="hl-value">"${status.expression}"</span> 
    <span class="hl-attribute">value</span>=<span class="hl-value">"$!status.value"</span> /&gt;&lt;<span class="hl-tag">br</span>&gt;
  #foreach($error in $status.errorMessages) &lt;<span class="hl-tag">b</span>&gt;$error&lt;<span class="hl-tag">/b</span>&gt; &lt;<span class="hl-tag">br</span>&gt; #end
  &lt;<span class="hl-tag">br</span>&gt;
  ... 
  &lt;<span class="hl-tag">input</span> <span class="hl-attribute">type</span>=<span class="hl-value">"submit"</span> <span class="hl-attribute">value</span>=<span class="hl-value">"submit"</span>/&gt;
&lt;<span class="hl-tag">/form</span>&gt;
...
&lt;<span class="hl-tag">/html</span>&gt;</pre><pre class="programlisting">&lt;<span class="hl-comment">!-- freemarker macros have to be imported into a namespace.  We strongly
recommend sticking to 'spring' --</span>&gt;
&lt;<span class="hl-tag">#import</span> <span class="hl-attribute">"spring.ftl"</span> <span class="hl-attribute">as</span> <span class="hl-attribute">spring</span> /&gt;
&lt;<span class="hl-tag">html</span>&gt;
...
&lt;<span class="hl-tag">form</span> <span class="hl-attribute">action</span>=<span class="hl-value">""</span> <span class="hl-attribute">method</span>=<span class="hl-value">"POST"</span>&gt;
  Name: 
  &lt;<span class="hl-tag">@spring.bind</span> <span class="hl-attribute">"command.name"</span> /&gt; 
  &lt;<span class="hl-tag">input</span> <span class="hl-attribute">type</span>=<span class="hl-value">"text"</span> 
    <span class="hl-attribute">name</span>=<span class="hl-value">"${spring.status.expression}"</span> 
    <span class="hl-attribute">value</span>=<span class="hl-value">"${spring.status.value?default("</span><span class="hl-attribute">")}"</span> /&gt;&lt;<span class="hl-tag">br</span>&gt;
  &lt;<span class="hl-tag">#list</span> <span class="hl-attribute">spring.status.errorMessages</span> <span class="hl-attribute">as</span> <span class="hl-attribute">error&gt;</span> <span class="hl-attribute">&lt;b&gt;${error}&lt;/b&gt;</span> <span class="hl-attribute">&lt;br&gt;</span> <span class="hl-attribute">&lt;/#list&gt;</span>
  <span class="hl-attribute">&lt;br&gt;</span>
  <span class="hl-attribute">...</span> 
  <span class="hl-attribute">&lt;input</span> <span class="hl-attribute">type</span>=<span class="hl-value">"submit"</span> <span class="hl-attribute">value</span>=<span class="hl-value">"submit"</span>/&gt;
&lt;<span class="hl-tag">/form</span>&gt;
...
&lt;<span class="hl-tag">/html</span>&gt;</pre><p><code class="literal">#springBind</code> /
        <code class="literal">&lt;@spring.bind&gt;</code> requires a 'path' argument
        which consists of the name of your command object (it will be
        'command' unless you changed it in your FormController properties)
        followed by a period and the name of the field on the command object
        you wish to bind to. Nested fields can be used too such as
        "command.address.street". The <code class="literal">bind</code> macro assumes
        the default HTML escaping behavior specified by the ServletContext
        parameter <code class="literal">defaultHtmlEscape</code> in web.xml</p><p>The optional form of the macro called
        <code class="literal">#springBindEscaped</code> /
        <code class="literal">&lt;@spring.bindEscaped&gt;</code> takes a second argument
        and explicitly specifies whether HTML escaping should be used in the
        status error messages or values. Set to true or false as required.
        Additional form handling macros simplify the use of HTML escaping and
        these macros should be used wherever possible. They are explained in
        the next section.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="views-form-macros"></a>16.4.5.3&nbsp;Form input generation macros</h4></div></div></div><p>Additional convenience macros for both languages simplify both
        binding and form generation (including validation error display). It
        is never necessary to use these macros to generate form input fields,
        and they can be mixed and matched with simple HTML or calls direct to
        the spring bind macros highlighted previously.</p><p>The following table of available macros show the VTL and FTL
        definitions and the parameter list that each takes.</p><div class="table"><a name="views-macros-defs-tbl"></a><p class="title"><b>Table&nbsp;16.1.&nbsp;Table of macro definitions</b></p><div class="table-contents"><table summary="Table of macro definitions" style="border-collapse: collapse;border-top: 1.0pt solid ; border-bottom: 1.0pt solid ; border-left: 1.0pt solid ; border-right: 1.0pt solid ; "><colgroup><col align="left"><col><col></colgroup><thead><tr><th style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; " align="center">macro</th><th style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; " align="center">VTL definition</th><th style="border-bottom: 1.0pt solid ; " align="center">FTL definition</th></tr></thead><tbody><tr><td style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; " align="left"><span class="bold"><strong>message</strong></span> (output a
                string from a resource bundle based on the code
                parameter)</td><td style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; "><code class="literal">#springMessage($code)</code></td><td style="border-bottom: 1.0pt solid ; "><code class="literal">&lt;@spring.message
                code/&gt;</code></td></tr><tr><td style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; " align="left"><span class="bold"><strong>messageText</strong></span> (output a
                string from a resource bundle based on the code parameter,
                falling back to the value of the default parameter)</td><td style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; "><code class="literal">#springMessageText($code
                $text)</code></td><td style="border-bottom: 1.0pt solid ; "><code class="literal">&lt;@spring.messageText code,
                text/&gt;</code></td></tr><tr><td style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; " align="left"><span class="bold"><strong>url</strong></span> (prefix a relative
                URL with the application's context root)</td><td style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; "><code class="literal">#springUrl($relativeUrl)</code></td><td style="border-bottom: 1.0pt solid ; "><code class="literal">&lt;@spring.url
                relativeUrl/&gt;</code></td></tr><tr><td style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; " align="left"><span class="bold"><strong>formInput</strong></span> (standard
                input field for gathering user input)</td><td style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; "><code class="literal">#springFormInput($path
                $attributes)</code></td><td style="border-bottom: 1.0pt solid ; "><code class="literal">&lt;@spring.formInput path, attributes,
                fieldType/&gt;</code></td></tr><tr><td style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; " align="left"><span class="bold"><strong>formHiddenInput *</strong></span>
                (hidden input field for submitting non-user input)</td><td style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; "><code class="literal">#springFormHiddenInput($path
                $attributes)</code></td><td style="border-bottom: 1.0pt solid ; "><code class="literal">&lt;@spring.formHiddenInput path,
                attributes/&gt;</code></td></tr><tr><td style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; " align="left"><span class="bold"><strong>formPasswordInput</strong></span> *
                (standard input field for gathering passwords. Note that no
                value will ever be populated in fields of this type)</td><td style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; "><code class="literal">#springFormPasswordInput($path
                $attributes)</code></td><td style="border-bottom: 1.0pt solid ; "><code class="literal">&lt;@spring.formPasswordInput path,
                attributes/&gt;</code></td></tr><tr><td style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; " align="left"><span class="bold"><strong>formTextarea</strong></span> (large
                text field for gathering long, freeform text input)</td><td style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; "><code class="literal">#springFormTextarea($path
                $attributes)</code></td><td style="border-bottom: 1.0pt solid ; "><code class="literal">&lt;@spring.formTextarea path,
                attributes/&gt;</code></td></tr><tr><td style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; " align="left"><span class="bold"><strong>formSingleSelect</strong></span> (drop
                down box of options allowing a single required value to be
                selected)</td><td style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; "><code class="literal">#springFormSingleSelect( $path $options
                $attributes)</code></td><td style="border-bottom: 1.0pt solid ; "><code class="literal">&lt;@spring.formSingleSelect path, options,
                attributes/&gt;</code></td></tr><tr><td style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; " align="left"><span class="bold"><strong>formMultiSelect</strong></span> (a
                list box of options allowing the user to select 0 or more
                values)</td><td style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; "><code class="literal">#springFormMultiSelect($path $options
                $attributes)</code></td><td style="border-bottom: 1.0pt solid ; "><code class="literal">&lt;@spring.formMultiSelect path, options,
                attributes/&gt;</code></td></tr><tr><td style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; " align="left"><span class="bold"><strong>formRadioButtons</strong></span> (a
                set of radio buttons allowing a single selection to be made
                from the available choices)</td><td style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; "><code class="literal">#springFormRadioButtons($path $options
                $separator $attributes)</code></td><td style="border-bottom: 1.0pt solid ; "><code class="literal">&lt;@spring.formRadioButtons path, options
                separator, attributes/&gt;</code></td></tr><tr><td style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; " align="left"><span class="bold"><strong>formCheckboxes</strong></span> (a set
                of checkboxes allowing 0 or more values to be
                selected)</td><td style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; "><code class="literal">#springFormCheckboxes($path $options
                $separator $attributes)</code></td><td style="border-bottom: 1.0pt solid ; "><code class="literal">&lt;@spring.formCheckboxes path, options,
                separator, attributes/&gt;</code></td></tr><tr><td style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; " align="left"><span class="bold"><strong>formCheckbox</strong></span> (a single
                checkbox)</td><td style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; "><code class="literal">#springFormCheckbox($path
                $attributes)</code></td><td style="border-bottom: 1.0pt solid ; "><code class="literal">&lt;@spring.formCheckbox path,
                attributes/&gt;</code></td></tr><tr><td style="border-right: 1.0pt solid ; " align="left"><span class="bold"><strong>showErrors</strong></span> (simplify
                display of validation errors for the bound field)</td><td style="border-right: 1.0pt solid ; "><code class="literal">#springShowErrors($separator
                $classOrStyle)</code></td><td style=""><code class="literal">&lt;@spring.showErrors separator,
                classOrStyle/&gt;</code></td></tr></tbody></table></div></div><br class="table-break"><p>* In FTL (FreeMarker), these two macros are not actually
        required as you can use the normal <code class="literal">formInput</code> macro,
        specifying '<code class="literal">hidden</code>' or
        '<code class="literal">password</code>' as the value for the
        <code class="literal">fieldType</code> parameter.</p><p>The parameters to any of the above macros have consistent
        meanings:</p><div class="itemizedlist"><ul type="disc"><li><p>path: the name of the field to bind to (ie
            "command.name")</p></li><li><p>options: a Map of all the available values that can be
            selected from in the input field. The keys to the map represent
            the values that will be POSTed back from the form and bound to the
            command object. Map objects stored against the keys are the labels
            displayed on the form to the user and may be different from the
            corresponding values posted back by the form. Usually such a map
            is supplied as reference data by the controller. Any Map
            implementation can be used depending on required behavior. For
            strictly sorted maps, a <code class="literal">SortedMap</code> such as a
            <code class="literal">TreeMap</code> with a suitable Comparator may be used
            and for arbitrary Maps that should return values in insertion
            order, use a <code class="literal">LinkedHashMap</code> or a
            <code class="literal">LinkedMap</code> from commons-collections.</p></li><li><p>separator: where multiple options are available as discreet
            elements (radio buttons or checkboxes), the sequence of characters
            used to separate each one in the list (ie "&lt;br&gt;").</p></li><li><p>attributes: an additional string of arbitrary tags or text
            to be included within the HTML tag itself. This string is echoed
            literally by the macro. For example, in a textarea field you may
            supply attributes as 'rows="5" cols="60"' or you could pass style
            information such as 'style="border:1px solid silver"'.</p></li><li><p>classOrStyle: for the showErrors macro, the name of the CSS
            class that the span tag wrapping each error will use. If no
            information is supplied (or the value is empty) then the errors
            will be wrapped in &lt;b&gt;&lt;/b&gt; tags.</p></li></ul></div><p>Examples of the macros are outlined below some in FTL and some
        in VTL. Where usage differences exist between the two languages, they
        are explained in the notes.</p><div class="section" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="views-form-macros-input"></a>Input Fields</h5></div></div></div><pre class="programlisting">&lt;<span class="hl-comment">!-- the Name field example from above using form macros in VTL --</span>&gt;
...
    Name:
    #springFormInput("command.name" "")&lt;<span class="hl-tag">br</span>&gt;
    #springShowErrors("&lt;<span class="hl-tag">br</span>&gt;" "")&lt;<span class="hl-tag">br</span>&gt;</pre><p>The formInput macro takes the path parameter (command.name)
          and an additional attributes parameter which is empty in the example
          above. The macro, along with all other form generation macros,
          performs an implicit spring bind on the path parameter. The binding
          remains valid until a new bind occurs so the showErrors macro
          doesn't need to pass the path parameter again - it simply operates
          on whichever field a bind was last created for.</p><p>The showErrors macro takes a separator parameter (the
          characters that will be used to separate multiple errors on a given
          field) and also accepts a second parameter, this time a class name
          or style attribute. Note that FreeMarker is able to specify default
          values for the attributes parameter, unlike Velocity, and the two
          macro calls above could be expressed as follows in FTL:</p><pre class="programlisting">&lt;<span class="hl-tag">@spring.formInput</span> <span class="hl-attribute">"command.name"/&gt;</span>
<span class="hl-attribute">&lt;@spring.showErrors</span> <span class="hl-attribute">"&lt;br&gt;"/&gt;</span></pre><p>Output is shown below of the form fragment generating the name
          field, and displaying a validation error after the form was
          submitted with no value in the field. Validation occurs through
          Spring's Validation framework.</p><p>The generated HTML looks like this:</p><pre class="programlisting">Name:
  &lt;input type="text" name="name" value=""     
&gt;
&lt;br&gt;
  &lt;b&gt;required&lt;/b&gt;
&lt;br&gt;
&lt;br&gt;</pre><p>The formTextarea macro works the same way as the formInput
          macro and accepts the same parameter list. Commonly, the second
          parameter (attributes) will be used to pass style information or
          rows and cols attributes for the textarea.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="views-form-macros-select"></a>Selection Fields</h5></div></div></div><p>Four selection field macros can be used to generate common UI
          value selection inputs in your HTML forms.</p><div class="itemizedlist"><ul type="disc"><li><p>formSingleSelect</p></li><li><p>formMultiSelect</p></li><li><p>formRadioButtons</p></li><li><p>formCheckboxes</p></li></ul></div><p>Each of the four macros accepts a Map of options containing
          the value for the form field, and the label corresponding to that
          value. The value and the label can be the same.</p><p>An example of radio buttons in FTL is below. The form backing
          object specifies a default value of 'London' for this field and so
          no validation is necessary. When the form is rendered, the entire
          list of cities to choose from is supplied as reference data in the
          model under the name 'cityMap'.</p><pre class="programlisting">...
  Town:
  &lt;@spring.formRadioButtons "command.address.town", cityMap, "" /&gt;&lt;br&gt;&lt;br&gt;</pre><p>This renders a line of radio buttons, one for each value in
          <code class="literal">cityMap</code> using the separator "". No additional
          attributes are supplied (the last parameter to the macro is
          missing). The cityMap uses the same String for each key-value pair
          in the map. The map's keys are what the form actually submits as
          POSTed request parameters, map values are the labels that the user
          sees. In the example above, given a list of three well known cities
          and a default value in the form backing object, the HTML would
          be</p><pre class="programlisting">Town:
&lt;input type="radio" name="address.town" value="London"
   
&gt;
London
&lt;input type="radio" name="address.town" value="Paris"
  checked="checked" 
&gt;
Paris
&lt;input type="radio" name="address.town" value="New York"
   
&gt;
New York</pre><p>If your application expects to handle cities by internal codes
          for example, the map of codes would be created with suitable keys
          like the example below.</p><pre class="programlisting"><span class="hl-keyword">protected</span> Map referenceData(HttpServletRequest request) <span class="hl-keyword">throws</span> Exception {
  Map cityMap = <span class="hl-keyword">new</span> LinkedHashMap();
  cityMap.put(<span class="hl-string">"LDN"</span>, <span class="hl-string">"London"</span>);
  cityMap.put(<span class="hl-string">"PRS"</span>, <span class="hl-string">"Paris"</span>);
  cityMap.put(<span class="hl-string">"NYC"</span>, <span class="hl-string">"New York"</span>);
  
  Map m = <span class="hl-keyword">new</span> HashMap();
  m.put(<span class="hl-string">"cityMap"</span>, cityMap);
  <span class="hl-keyword">return</span> m;
}</pre><p>The code would now produce output where the radio values are
          the relevant codes but the user still sees the more user friendly
          city names.</p><pre class="programlisting">Town:
&lt;input type="radio" name="address.town" value="LDN"
   
&gt;
London
&lt;input type="radio" name="address.town" value="PRS"
  checked="checked" 
&gt;
Paris
&lt;input type="radio" name="address.town" value="NYC"
   
&gt;
New York</pre></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="views-form-macros-html-escaping"></a>16.4.5.4&nbsp;HTML escaping and XHTML compliance</h4></div></div></div><p>Default usage of the form macros above will result in HTML tags
        that are HTML 4.01 compliant and that use the default value for HTML
        escaping defined in your web.xml as used by Spring's bind support. In
        order to make the tags XHTML compliant or to override the default HTML
        escaping value, you can specify two variables in your template (or in
        your model where they will be visible to your templates). The
        advantage of specifying them in the templates is that they can be
        changed to different values later in the template processing to
        provide different behavior for different fields in your form.</p><p>To switch to XHTML compliance for your tags, specify a value of
        'true' for a model/context variable named xhtmlCompliant:</p><pre class="programlisting">## for Velocity..
#set($springXhtmlCompliant = true)

&lt;#-- for FreeMarker --&gt;
&lt;#assign xhtmlCompliant = true in spring&gt;</pre><p>Any tags generated by the Spring macros will now be XHTML
        compliant after processing this directive.</p><p>In similar fashion, HTML escaping can be specified per
        field:</p><pre class="programlisting">&lt;<span class="hl-tag">#--</span> <span class="hl-attribute">until</span> <span class="hl-attribute">this</span> <span class="hl-attribute">point,</span> <span class="hl-attribute">default</span> <span class="hl-attribute">HTML</span> <span class="hl-attribute">escaping</span> <span class="hl-attribute">is</span> <span class="hl-attribute">used</span> <span class="hl-attribute">--&gt;</span>

<span class="hl-attribute">&lt;#assign</span> <span class="hl-attribute">htmlEscape</span> = <span class="hl-value">true</span> <span class="hl-attribute">in</span> <span class="hl-attribute">spring&gt;</span>
<span class="hl-attribute">&lt;#--</span> <span class="hl-attribute">next</span> <span class="hl-attribute">field</span> <span class="hl-attribute">will</span> <span class="hl-attribute">use</span> <span class="hl-attribute">HTML</span> <span class="hl-attribute">escaping</span> <span class="hl-attribute">--&gt;</span>
<span class="hl-attribute">&lt;@spring.formInput</span> <span class="hl-attribute">"command.name"</span> /&gt;

&lt;<span class="hl-tag">#assign</span> <span class="hl-attribute">htmlEscape</span> = <span class="hl-value">false</span> <span class="hl-attribute">in</span> <span class="hl-attribute">spring&gt;</span>
<span class="hl-attribute">&lt;#--</span> <span class="hl-attribute">all</span> <span class="hl-attribute">future</span> <span class="hl-attribute">fields</span> <span class="hl-attribute">will</span> <span class="hl-attribute">be</span> <span class="hl-attribute">bound</span> <span class="hl-attribute">with</span> <span class="hl-attribute">HTML</span> <span class="hl-attribute">escaping</span> <span class="hl-attribute">off</span> <span class="hl-attribute">--&gt;</span></pre></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="view-xslt"></a>16.5&nbsp;XSLT</h2></div></div></div><p>XSLT is a transformation language for XML and is popular as a view
    technology within web applications. XSLT can be a good choice as a view
    technology if your application naturally deals with XML, or if your model
    can easily be converted to XML. The following section shows how to produce
    an XML document as model data and have it transformed with XSLT in a
    Spring Web MVC application.</p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="view-xslt-firstwords"></a>16.5.1&nbsp;My First Words</h3></div></div></div><p>This example is a trivial Spring application that creates a list
      of words in the <code class="interfacename">Controller</code> and adds them
      to the model map. The map is returned along with the view name of our
      XSLT view. See <a class="xref" href="mvc.html#mvc-controller" title="15.3&nbsp;Implementing Controllers">Section&nbsp;15.3, &#8220;Implementing Controllers&#8221;</a> for details of Spring Web MVC's
      <code class="interfacename">Controller</code> interface. The XSLT view will
      turn the list of words into a simple XML document ready for
      transformation.</p><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="view-xslt-beandefs"></a>16.5.1.1&nbsp;Bean definitions</h4></div></div></div><p>Configuration is standard for a simple Spring application. The
        dispatcher servlet config file contains a reference to a
        <code class="interfacename">ViewResolver</code>, URL mappings and a single
        controller bean...</p><pre class="programlisting">&lt;<span class="hl-tag">bean</span> <span class="hl-attribute">id</span>=<span class="hl-value">"homeController"</span><span class="hl-attribute">class</span>=<span class="hl-value">"xslt.HomeController"</span>/&gt;</pre><p>... that encapsulates our word generation logic.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="view-xslt-controllercode"></a>16.5.1.2&nbsp;Standard MVC controller code</h4></div></div></div><p>The controller logic is encapsulated in a subclass of
        <code class="classname">AbstractController</code>, with the handler method
        being defined like so...</p><pre class="programlisting"><span class="hl-keyword">protected</span> ModelAndView handleRequestInternal(
    HttpServletRequest request,
    HttpServletResponse response) <span class="hl-keyword">throws</span> Exception {
        
    Map map = <span class="hl-keyword">new</span> HashMap();
    List wordList = <span class="hl-keyword">new</span> ArrayList();
        
    wordList.add(<span class="hl-string">"hello"</span>);
    wordList.add(<span class="hl-string">"world"</span>);
       
    map.put(<span class="hl-string">"wordList"</span>, wordList);
      
    <span class="hl-keyword">return</span> <span class="hl-keyword">new</span> ModelAndView(<span class="hl-string">"home"</span>, map);
}</pre><p>So far we've done nothing that's XSLT specific. The model data
        has been created in the same way as you would for any other Spring MVC
        application. Depending on the configuration of the application now,
        that list of words could be rendered by JSP/JSTL by having them added
        as request attributes, or they could be handled by Velocity by adding
        the object to the <code class="classname">VelocityContext</code>. In order to
        have XSLT render them, they of course have to be converted into an XML
        document somehow. There are software packages available that will
        automatically 'domify' an object graph, but within Spring, you have
        complete flexibility to create the DOM from your model in any way you
        choose. This prevents the transformation of XML playing too great a
        part in the structure of your model data which is a danger when using
        tools to manage the domification process.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="view-xslt-subclassing"></a>16.5.1.3&nbsp;Convert the model data to XML</h4></div></div></div><p>In order to create a DOM document from our list of words or any
        other model data, we must subclass the (provided)
        <code class="classname">org.springframework.web.servlet.view.xslt.AbstractXsltView</code>
        class. In doing so, we must also typically implement the abstract
        method <code class="methodname">createXsltSource(..)</code> method. The first
        parameter passed to this method is our model map. Here's the complete
        listing of the <code class="classname">HomePage</code> class in our trivial
        word application:</p><pre class="programlisting">
<span class="hl-keyword">package</span> xslt;

<span class="hl-comment">// imports omitted for brevity</span>

<span class="hl-keyword">public</span> <span class="hl-keyword">class</span> HomePage <span class="hl-keyword">extends</span> AbstractXsltView {

    <span class="hl-keyword">protected</span> Source createXsltSource(Map model, String rootName, HttpServletRequest
        request, HttpServletResponse response) <span class="hl-keyword">throws</span> Exception {

        Document document = DocumentBuilderFactory.newInstance().newDocumentBuilder().newDocument();
        Element root = document.createElement(rootName);

        List words = (List) model.get(<span class="hl-string">"wordList"</span>);
        <span class="hl-keyword">for</span> (Iterator it = words.iterator(); it.hasNext();) {
            String nextWord = (String) it.next();
            Element wordNode = document.createElement(<span class="hl-string">"word"</span>);
            Text textNode = document.createTextNode(nextWord);
            wordNode.appendChild(textNode);
            root.appendChild(wordNode);
        }
        <span class="hl-keyword">return</span> <span class="hl-keyword">new</span> DOMSource(root);
    }

}</pre><p>A series of parameter name/value pairs can optionally be defined
        by your subclass which will be added to the transformation object. The
        parameter names must match those defined in your XSLT template
        declared with <code class="literal">&lt;xsl:param
        name="myParam"&gt;defaultValue&lt;/xsl:param&gt;</code>. To specify
        the parameters, override the <code class="methodname">getParameters()</code>
        method of the <code class="classname">AbstractXsltView</code> class and return
        a <code class="interfacename">Map</code> of the name/value pairs. If your
        parameters need to derive information from the current request, you
        can override the <code class="methodname">getParameters(HttpServletRequest
        request)</code> method instead.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="view-xslt-viewdefinitions"></a>16.5.1.4&nbsp;Defining the view properties</h4></div></div></div><p>The views.properties file (or equivalent xml definition if
        you're using an XML based view resolver as we did in the Velocity
        examples above) looks like this for the one-view application that is
        'My First Words':</p><pre class="programlisting">home.(class)=xslt.HomePage
home.stylesheetLocation=/WEB-INF/xsl/home.xslt
home.root=words</pre><p>Here, you can see how the view is tied in with the
        <code class="classname">HomePage</code> class just written which handles the
        model domification in the first property <code class="literal">'.(class)'</code>.
        The <code class="literal">'stylesheetLocation'</code> property points to the
        XSLT file which will handle the XML transformation into HTML for us
        and the final property <code class="literal">'.root'</code> is the name that
        will be used as the root of the XML document. This gets passed to the
        <code class="classname">HomePage</code> class above in the second parameter to
        the <code class="methodname">createXsltSource(..)</code> method(s).</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="view-xslt-transforming"></a>16.5.1.5&nbsp;Document transformation</h4></div></div></div><p>Finally, we have the XSLT code used for transforming the above
        document. As shown in the above
        <code class="filename">'views.properties'</code> file, the stylesheet is called
        <code class="filename">'home.xslt'</code> and it lives in the war file in the
        <code class="filename">'WEB-INF/xsl'</code> directory.</p><pre class="programlisting">&lt;<span class="hl-tag">?xml version="1.0" encoding="utf-8"?</span>&gt;
&lt;<span class="hl-tag">xsl:stylesheet</span> <span class="hl-attribute">version</span>=<span class="hl-value">"1.0"</span> <span class="hl-attribute">xmlns:xsl</span>=<span class="hl-value">"http://www.w3.org/1999/XSL/Transform"</span>&gt;

    &lt;<span class="hl-tag">xsl:output</span> <span class="hl-attribute">method</span>=<span class="hl-value">"html"</span> <span class="hl-attribute">omit-xml-declaration</span>=<span class="hl-value">"yes"</span>/&gt;

    &lt;<span class="hl-tag">xsl:template</span> <span class="hl-attribute">match</span>=<span class="hl-value">"/"</span>&gt;
        &lt;<span class="hl-tag">html</span>&gt;
            &lt;<span class="hl-tag">head</span>&gt;&lt;<span class="hl-tag">title</span>&gt;Hello!&lt;<span class="hl-tag">/title</span>&gt;&lt;<span class="hl-tag">/head</span>&gt;
            &lt;<span class="hl-tag">body</span>&gt;
                &lt;<span class="hl-tag">h1</span>&gt;My First Words&lt;<span class="hl-tag">/h1</span>&gt;
                &lt;<span class="hl-tag">xsl:apply-templates</span>/&gt;
            &lt;<span class="hl-tag">/body</span>&gt;
        &lt;<span class="hl-tag">/html</span>&gt;
    &lt;<span class="hl-tag">/xsl:template</span>&gt;

    &lt;<span class="hl-tag">xsl:template</span> <span class="hl-attribute">match</span>=<span class="hl-value">"word"</span>&gt;
        &lt;<span class="hl-tag">xsl:value-of</span> <span class="hl-attribute">select</span>=<span class="hl-value">"."</span>/&gt;&lt;<span class="hl-tag">br</span>/&gt;
    &lt;<span class="hl-tag">/xsl:template</span>&gt;

&lt;<span class="hl-tag">/xsl:stylesheet</span>&gt;</pre></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="view-xslt-summary"></a>16.5.2&nbsp;Summary</h3></div></div></div><p>A summary of the files discussed and their location in the WAR
      file is shown in the simplified WAR structure below.</p><pre class="programlisting">ProjectRoot
  |
  +- WebContent
      |
      +- WEB-INF
          |
          +- classes
          |    |
          |    +- xslt
          |    |   |
          |    |   +- HomePageController.class 
          |    |   +- HomePage.class
          |    |
          |    +- views.properties
          |
          +- lib
          |   |
          |   +- spring-*.jar
          |
          +- xsl
          |   |
          |   +- home.xslt
          |
          +- frontcontroller-servlet.xml</pre><p>You will also need to ensure that an XML parser and an XSLT engine
      are available on the classpath. JDK 1.4 provides them by default, and
      most Java EE containers will also make them available by default, but it's
      a possible source of errors to be aware of.</p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="view-document"></a>16.6&nbsp;Document views (PDF/Excel)</h2></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="view-document-intro"></a>16.6.1&nbsp;Introduction</h3></div></div></div><p>Returning an HTML page isn't always the best way for the user to
      view the model output, and Spring makes it simple to generate a PDF
      document or an Excel spreadsheet dynamically from the model data. The
      document is the view and will be streamed from the server with the
      correct content type to (hopefully) enable the client PC to run their
      spreadsheet or PDF viewer application in response.</p><p>In order to use Excel views, you need to add the 'poi' library to
      your classpath, and for PDF generation, the iText library.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="view-document-config"></a>16.6.2&nbsp;Configuration and setup</h3></div></div></div><p>Document based views are handled in an almost identical fashion to
      XSLT views, and the following sections build upon the previous one by
      demonstrating how the same controller used in the XSLT example is
      invoked to render the same model as both a PDF document and an Excel
      spreadsheet (which can also be viewed or manipulated in Open
      Office).</p><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="view-document-configviews"></a>16.6.2.1&nbsp;Document view definitions</h4></div></div></div><p>First, let's amend the views.properties file (or xml
        equivalent) and add a simple view definition for both document types.
        The entire file now looks like this with the XSLT view shown from
        earlier:</p><pre class="programlisting">home.(class)=xslt.HomePage
home.stylesheetLocation=/WEB-INF/xsl/home.xslt
home.root=words

xl.(class)=excel.HomePage

pdf.(class)=pdf.HomePage</pre><p><span class="emphasis"><em>If you want to start with a
        template spreadsheet or a fillable PDF form to add your model data to, specify the location
        as the 'url' property in the view definition</em></span></p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="view-document-configcontroller"></a>16.6.2.2&nbsp;Controller code</h4></div></div></div><p>The controller code we'll use remains exactly the same from the
        XSLT example earlier other than to change the name of the view to use.
        Of course, you could be clever and have this selected based on a URL
        parameter or some other logic - proof that Spring really is very good
        at decoupling the views from the controllers!</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="view-document-configsubclasses"></a>16.6.2.3&nbsp;Subclassing for Excel views</h4></div></div></div><p>Exactly as we did for the XSLT example, we'll subclass suitable
        abstract classes in order to implement custom behavior in generating
        our output documents. For Excel, this involves writing a subclass of
        <code class="literal">org.springframework.web.servlet.view.document.AbstractExcelView</code>
        (for Excel files generated by POI) or
        <code class="literal">org.springframework.web.servlet.view.document.AbstractJExcelView</code>
        (for JExcelApi-generated Excel files) and implementing the
        <code class="literal">buildExcelDocument()</code> method.</p><p>Here's the complete listing for our POI Excel view which
        displays the word list from the model map in consecutive rows of the
        first column of a new spreadsheet:</p><pre class="programlisting"><span class="hl-keyword">package</span> excel;

<span class="hl-comment">// imports omitted for brevity</span>

<span class="hl-keyword">public</span> <span class="hl-keyword">class</span> HomePage <span class="hl-keyword">extends</span> AbstractExcelView {

    <span class="hl-keyword">protected</span> <span class="hl-keyword">void</span> buildExcelDocument(
        Map model,
        HSSFWorkbook wb,
        HttpServletRequest req,
        HttpServletResponse resp)
        <span class="hl-keyword">throws</span> Exception {
    
        HSSFSheet sheet;
        HSSFRow sheetRow;
        HSSFCell cell;

        <span class="hl-comment">// Go to the first sheet</span>
        <span class="hl-comment">// getSheetAt: only if wb is created from an existing document</span>
        <span class="hl-comment">// sheet = wb.getSheetAt(0);</span>
        sheet = wb.createSheet(<span class="hl-string">"Spring"</span>);
        sheet.setDefaultColumnWidth((<span class="hl-keyword">short</span>) 12);

        <span class="hl-comment">// write a text at A1</span>
        cell = getCell(sheet, 0, 0);
        setText(cell, <span class="hl-string">"Spring-Excel test"</span>);

        List words = (List) model.get(<span class="hl-string">"wordList"</span>);
        <span class="hl-keyword">for</span> (<span class="hl-keyword">int</span> i=0; i &lt; words.size(); i++) {
            cell = getCell(sheet, 2+i, 0);
            setText(cell, (String) words.get(i));

        }
    }
}</pre><p>And the following is a view generating the same Excel file, now using
        JExcelApi:</p><pre class="programlisting"><span class="hl-keyword">package</span> excel;

<span class="hl-comment">// imports omitted for brevity</span>

<span class="hl-keyword">public</span> <span class="hl-keyword">class</span> HomePage <span class="hl-keyword">extends</span> AbstractJExcelView {

    <span class="hl-keyword">protected</span> <span class="hl-keyword">void</span> buildExcelDocument(Map model,
        WritableWorkbook wb,
        HttpServletRequest request,
        HttpServletResponse response)
    <span class="hl-keyword">throws</span> Exception {
			
        WritableSheet sheet = wb.createSheet(<span class="hl-string">"Spring"</span>, 0);

        sheet.addCell(<span class="hl-keyword">new</span> Label(0, 0, <span class="hl-string">"Spring-Excel test"</span>));
		
        List words = (List) model.get(<span class="hl-string">"wordList"</span>);
        <span class="hl-keyword">for</span> (<span class="hl-keyword">int</span> i = 0; i &lt; words.size(); i++) {
            sheet.addCell(<span class="hl-keyword">new</span> Label(2+i, 0, (String) words.get(i)));
        }
    }
}</pre><p>Note the differences between the APIs. We've found that the
        JExcelApi is somewhat more intuitive, and furthermore, JExcelApi has
        slightly better image-handling capabilities. There have been memory
        problems with large Excel files when using JExcelApi however.</p><p>If you now amend the controller such that it returns
        <code class="literal">xl</code> as the name of the view (<code class="literal">return new
        ModelAndView("xl", map);</code>) and run your application again,
        you should find that the Excel spreadsheet is created and downloaded
        automatically when you request the same page as before.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="view-document-configsubclasspdf"></a>16.6.2.4&nbsp;Subclassing for PDF views</h4></div></div></div><p>The PDF version of the word list is even simpler. This time, the
        class extends
        <code class="literal">org.springframework.web.servlet.view.document.AbstractPdfView</code>
        and implements the <code class="literal">buildPdfDocument()</code> method as
        follows:</p><pre class="programlisting"><span class="hl-keyword">package</span> pdf;

<span class="hl-comment">// imports omitted for brevity</span>

<span class="hl-keyword">public</span> <span class="hl-keyword">class</span> PDFPage <span class="hl-keyword">extends</span> AbstractPdfView {

    <span class="hl-keyword">protected</span> <span class="hl-keyword">void</span> buildPdfDocument(
        Map model,
        Document doc,
        PdfWriter writer,
        HttpServletRequest req,
        HttpServletResponse resp)
        <span class="hl-keyword">throws</span> Exception {
        
        List words = (List) model.get(<span class="hl-string">"wordList"</span>);
        
        <span class="hl-keyword">for</span> (<span class="hl-keyword">int</span> i=0; i&lt;words.size(); i++)
            doc.add( <span class="hl-keyword">new</span> Paragraph((String) words.get(i)));
    
    }
}</pre><p>Once again, amend the controller to return the
        <code class="literal">pdf</code> view with <code class="literal">return new
        ModelAndView("pdf", map);</code>, and reload the URL in your
        application. This time a PDF document should appear listing each of
        the words in the model map.</p></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="view-jasper-reports"></a>16.7&nbsp;JasperReports</h2></div></div></div><p>JasperReports (<a class="ulink" href="http://jasperreports.sourceforge.net" target="_top">http://jasperreports.sourceforge.net</a>) is a powerful
    open-source reporting engine that supports the creation of report designs
    using an easily understood XML file format. JasperReports is capable of
    rendering reports in four different formats: CSV, Excel, HTML and
    PDF.</p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="view-jasper-reports-dependencies"></a>16.7.1&nbsp;Dependencies</h3></div></div></div><p>Your application will need to include the latest release of
      JasperReports, which at the time of writing was 0.6.1. JasperReports
      itself depends on the following projects:</p><div class="itemizedlist"><ul type="bullet"><li style="list-style-type: disc"><p>BeanShell</p></li><li style="list-style-type: disc"><p>Commons BeanUtils</p></li><li style="list-style-type: disc"><p>Commons Collections</p></li><li style="list-style-type: disc"><p>Commons Digester</p></li><li style="list-style-type: disc"><p>Commons Logging</p></li><li style="list-style-type: disc"><p>iText</p></li><li style="list-style-type: disc"><p>POI</p></li></ul></div><p>JasperReports also requires a JAXP compliant XML parser.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="view-jasper-reports-configuration"></a>16.7.2&nbsp;Configuration</h3></div></div></div><p>To configure JasperReports views in your Spring container
      configuration you need to define a
      <code class="interfacename">ViewResolver</code> to map view names to the
      appropriate view class depending on which format you want your report
      rendered in.</p><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="view-jasper-reports-configuration-resolver"></a>16.7.2.1&nbsp;Configuring the
        <code class="interfacename">ViewResolver</code></h4></div></div></div><p>Typically, you will use the
        <code class="classname">ResourceBundleViewResolver</code> to map view names to
        view classes and files in a properties file.</p><pre class="programlisting">&lt;<span class="hl-tag">bean</span> <span class="hl-attribute">id</span>=<span class="hl-value">"viewResolver"</span> <span class="hl-attribute">class</span>=<span class="hl-value">"org.springframework.web.servlet.view.ResourceBundleViewResolver"</span>&gt;
    &lt;<span class="hl-tag">property</span> <span class="hl-attribute">name</span>=<span class="hl-value">"basename"</span> <span class="hl-attribute">value</span>=<span class="hl-value">"views"</span>/&gt;
&lt;<span class="hl-tag">/bean</span>&gt;</pre><p>Here we've configured an instance of the
        <code class="classname">ResourceBundleViewResolver</code> class that will look
        for view mappings in the resource bundle with base name
        <code class="literal">views</code>. (The content of this file is described in
        the next section.)</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="view-jasper-reports-configuration-views"></a>16.7.2.2&nbsp;Configuring the <code class="literal">View</code>s</h4></div></div></div><p>The Spring Framework contains five different
        <code class="interfacename">View</code> implementations for JasperReports,
        four of which correspond to one of the four output formats supported
        by JasperReports, and one that allows for the format to be determined
        at runtime:</p><div class="table"><a name="view-jasper-reports-configuration-views-classes"></a><p class="title"><b>Table&nbsp;16.2.&nbsp;JasperReports <code class="interfacename">View</code>
          classes</b></p><div class="table-contents"><table summary="JasperReports View&#xA;          classes" style="border-collapse: collapse;border-top: 1.0pt solid ; border-bottom: 1.0pt solid ; border-left: 1.0pt solid ; border-right: 1.0pt solid ; "><colgroup><col><col></colgroup><thead><tr><th style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; ">Class Name</th><th style="border-bottom: 1.0pt solid ; ">Render Format</th></tr></thead><tbody><tr><td style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; "><code class="classname">JasperReportsCsvView</code></td><td style="border-bottom: 1.0pt solid ; ">CSV</td></tr><tr><td style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; "><code class="classname">JasperReportsHtmlView</code></td><td style="border-bottom: 1.0pt solid ; ">HTML</td></tr><tr><td style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; "><code class="classname">JasperReportsPdfView</code></td><td style="border-bottom: 1.0pt solid ; ">PDF</td></tr><tr><td style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; "><code class="classname">JasperReportsXlsView</code></td><td style="border-bottom: 1.0pt solid ; ">Microsoft Excel</td></tr><tr><td style="border-right: 1.0pt solid ; "><code class="classname">JasperReportsMultiFormatView</code></td><td style="">The view is <a class="link" href="view.html#view-jasper-reports-configuration-multiformat-view" title="16.7.2.4&nbsp;Using JasperReportsMultiFormatView">decided
                upon at runtime</a></td></tr></tbody></table></div></div><br class="table-break"><p>Mapping one of these classes to a view name and a report file is
        a matter of adding the appropriate entries in the resource bundle
        configured in the previous section as shown here:</p><pre class="programlisting">simpleReport.(class)=org.springframework.web.servlet.view.jasperreports.JasperReportsPdfView
simpleReport.url=/WEB-INF/reports/DataSourceReport.jasper</pre><p>Here you can see that the view with name
        <code class="literal">simpleReport</code> is mapped to the
        <code class="classname">JasperReportsPdfView</code> class, causing the output
        of this report to be rendered in PDF format. The
        <code class="literal">url</code> property of the view is set to the location of
        the underlying report file.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="view-jasper-reports-configuration-report-files"></a>16.7.2.3&nbsp;About Report Files</h4></div></div></div><p>JasperReports has two distinct types of report file: the design
        file, which has a <code class="literal">.jrxml</code> extension, and the
        compiled report file, which has a <code class="literal">.jasper</code>
        extension. Typically, you use the JasperReports Ant task to compile
        your <code class="literal">.jrxml</code> design file into a
        <code class="literal">.jasper</code> file before deploying it into your
        application. With the Spring Framework you can map either of these
        files to your report file and the framework will take care of
        compiling the <code class="literal">.jrxml</code> file on the fly for you. You
        should note that after a <code class="literal">.jrxml</code> file is compiled by
        the Spring Framework, the compiled report is cached for the lifetime
        of the application. Thus, to make changes to the file you will need to
        restart your application.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="view-jasper-reports-configuration-multiformat-view"></a>16.7.2.4&nbsp;Using
        <code class="classname">JasperReportsMultiFormatView</code></h4></div></div></div><p>The <code class="classname">JasperReportsMultiFormatView</code> allows
        for the report format to be specified at runtime. The actual rendering of
        the report is delegated to one of the other JasperReports view classes
        - the <code class="classname">JasperReportsMultiFormatView</code> class simply
        adds a wrapper layer that allows for the exact implementation to be
        specified at runtime.</p><p>The <code class="classname">JasperReportsMultiFormatView</code> class
        introduces two concepts: the format key and the discriminator key. The
        <code class="classname">JasperReportsMultiFormatView</code> class uses the
        mapping key to look up the actual view implementation class, and it uses
        the format key to lookup up the mapping key. From a coding perspective
        you add an entry to your model with the format key as the key and the
        mapping key as the value, for example:</p><pre class="programlisting"><span class="hl-keyword">public</span> ModelAndView handleSimpleReportMulti(HttpServletRequest request,
HttpServletResponse response) <span class="hl-keyword">throws</span> Exception {

  String uri = request.getRequestURI();
  String format = uri.substring(uri.lastIndexOf(<span class="hl-string">"."</span>) + 1);

  Map model = getModel();
  model.put(<span class="hl-string">"format"</span>, format);

  <span class="hl-keyword">return</span> <span class="hl-keyword">new</span> ModelAndView(<span class="hl-string">"simpleReportMulti"</span>, model);
}</pre><p>In this example, the mapping key is determined from the
        extension of the request URI and is added to the model under the
        default format key: <code class="literal">format</code>. If you wish to use a
        different format key then you can configure this using the
        <code class="literal">formatKey</code> property of the
        <code class="classname">JasperReportsMultiFormatView</code> class.</p><p>By default the following mapping key mappings are configured in
        <code class="classname">JasperReportsMultiFormatView</code>:</p><div class="table"><a name="view-jasper-reports-configuration-multiformat-view-mappings"></a><p class="title"><b>Table&nbsp;16.3.&nbsp;<code class="classname">JasperReportsMultiFormatView</code> Default
          Mapping Key Mappings</b></p><div class="table-contents"><table summary="JasperReportsMultiFormatView Default&#xA;          Mapping Key Mappings" style="border-collapse: collapse;border-top: 1.0pt solid ; border-bottom: 1.0pt solid ; border-left: 1.0pt solid ; border-right: 1.0pt solid ; "><colgroup><col><col></colgroup><thead><tr><th style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; ">Mapping Key</th><th style="border-bottom: 1.0pt solid ; ">View Class</th></tr></thead><tbody><tr><td style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; ">csv</td><td style="border-bottom: 1.0pt solid ; "><code class="classname">JasperReportsCsvView</code></td></tr><tr><td style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; ">html</td><td style="border-bottom: 1.0pt solid ; "><code class="classname">JasperReportsHtmlView</code></td></tr><tr><td style="border-right: 1.0pt solid ; border-bottom: 1.0pt solid ; ">pdf</td><td style="border-bottom: 1.0pt solid ; "><code class="classname">JasperReportsPdfView</code></td></tr><tr><td style="border-right: 1.0pt solid ; ">xls</td><td style=""><code class="classname">JasperReportsXlsView</code></td></tr></tbody></table></div></div><br class="table-break"><p>So in the example above a request to URI /foo/myReport.pdf would
        be mapped to the <code class="literal">JasperReportsPdfView</code> class. You
        can override the mapping key to view class mappings using the
        <code class="literal">formatMappings</code> property of
        <code class="classname">JasperReportsMultiFormatView</code>.</p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="view-jasper-reports-model"></a>16.7.3&nbsp;Populating the <code class="classname">ModelAndView</code></h3></div></div></div><p>In order to render your report correctly in the format you have
      chosen, you must supply Spring with all of the data needed to populate
      your report. For JasperReports this means you must pass in all report
      parameters along with the report datasource. Report parameters are
      simple name/value pairs and can be added to the
      <code class="interfacename">Map</code> for your model as you would add any
      name/value pair.</p><p>When adding the datasource to the model you have two approaches to
      choose from. The first approach is to add an instance of
      <code class="classname">JRDataSource</code> or a
      <code class="interfacename">Collection</code> type to the model
      <code class="interfacename">Map</code> under any arbitrary key. Spring will
      then locate this object in the model and treat it as the report
      datasource. For example, you may populate your model like so:</p><pre class="programlisting"><span class="hl-keyword">private</span> Map getModel() {
  Map model = <span class="hl-keyword">new</span> HashMap();
  Collection beanData = getBeanData();
  model.put(<span class="hl-string">"myBeanData"</span>, beanData);
  <span class="hl-keyword">return</span> model;
}</pre><p>The second approach is to add the instance of
      <code class="literal">JRDataSource</code> or <code class="literal">Collection</code> under a
      specific key and then configure this key using the
      <code class="literal">reportDataKey</code> property of the view class. In both
      cases Spring will wrap instances of <code class="literal">Collection</code> in a
      <code class="literal">JRBeanCollectionDataSource</code> instance. For
      example:</p><pre class="programlisting"><span class="hl-keyword">private</span> Map getModel() {
  Map model = <span class="hl-keyword">new</span> HashMap();
  Collection beanData = getBeanData();
  Collection someData = getSomeData();
  model.put(<span class="hl-string">"myBeanData"</span>, beanData);
  model.put(<span class="hl-string">"someData"</span>, someData);
  <span class="hl-keyword">return</span> model;
}</pre><p>Here you can see that two <code class="literal">Collection</code> instances
      are being added to the model. To ensure that the correct one is used, we
      simply modify our view configuration as appropriate:</p><pre class="programlisting">simpleReport.(class)=org.springframework.web.servlet.view.jasperreports.JasperReportsPdfView
simpleReport.url=/WEB-INF/reports/DataSourceReport.jasper
simpleReport.reportDataKey=myBeanData</pre><p>Be aware that when using the first approach, Spring will use the
      first instance of <code class="literal">JRDataSource</code> or
      <code class="literal">Collection</code> that it encounters. If you need to place
      multiple instances of <code class="literal">JRDataSource</code> or
      <code class="literal">Collection</code> into the model you need to use the
      second approach.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="view-jasper-reports-subreports"></a>16.7.4&nbsp;Working with Sub-Reports</h3></div></div></div><p>JasperReports provides support for embedded sub-reports within
      your master report files. There are a wide variety of mechanisms for
      including sub-reports in your report files. The easiest way is to hard
      code the report path and the SQL query for the sub report into your
      design files. The drawback of this approach is obvious: the values are
      hard-coded into your report files reducing reusability and making it
      harder to modify and update report designs. To overcome this you can
      configure sub-reports declaratively, and you can include additional data
      for these sub-reports directly from your controllers.</p><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="view-jasper-reports-subreports-config-reports"></a>16.7.4.1&nbsp;Configuring Sub-Report Files</h4></div></div></div><p>To control which sub-report files are included in a master
        report using Spring, your report file must be configured to accept
        sub-reports from an external source. To do this you declare a
        parameter in your report file like so:</p><pre class="programlisting">&lt;<span class="hl-tag">parameter</span> <span class="hl-attribute">name</span>=<span class="hl-value">"ProductsSubReport"</span> <span class="hl-attribute">class</span>=<span class="hl-value">"net.sf.jasperreports.engine.JasperReport"</span>/&gt;</pre><p>Then, you define your sub-report to use this sub-report
        parameter:</p><pre class="programlisting">&lt;<span class="hl-tag">subreport</span>&gt;
    &lt;<span class="hl-tag">reportElement</span> <span class="hl-attribute">isPrintRepeatedValues</span>=<span class="hl-value">"false"</span> <span class="hl-attribute">x</span>=<span class="hl-value">"5"</span> <span class="hl-attribute">y</span>=<span class="hl-value">"25"</span> <span class="hl-attribute">width</span>=<span class="hl-value">"325"</span>
        <span class="hl-attribute">height</span>=<span class="hl-value">"20"</span> <span class="hl-attribute">isRemoveLineWhenBlank</span>=<span class="hl-value">"true"</span> <span class="hl-attribute">backcolor</span>=<span class="hl-value">"#ffcc99"</span>/&gt;
    &lt;<span class="hl-tag">subreportParameter</span> <span class="hl-attribute">name</span>=<span class="hl-value">"City"</span>&gt;
        &lt;<span class="hl-tag">subreportParameterExpression</span>&gt;&lt;<span class="hl-tag">![CDATA[$F{city}]]</span>&gt;&lt;<span class="hl-tag">/subreportParameterExpression</span>&gt;
    &lt;<span class="hl-tag">/subreportParameter</span>&gt;
    &lt;<span class="hl-tag">dataSourceExpression</span>&gt;&lt;<span class="hl-tag">![CDATA[$P{SubReportData}]]</span>&gt;&lt;<span class="hl-tag">/dataSourceExpression</span>&gt;
    &lt;<span class="hl-tag">subreportExpression</span> <span class="hl-attribute">class</span>=<span class="hl-value">"net.sf.jasperreports.engine.JasperReport"</span>&gt;
                  &lt;<span class="hl-tag">![CDATA[$P{ProductsSubReport}]]</span>&gt;&lt;<span class="hl-tag">/subreportExpression</span>&gt;
&lt;<span class="hl-tag">/subreport</span>&gt;</pre><p>This defines a master report file that expects the sub-report to
        be passed in as an instance of
        <code class="literal">net.sf.jasperreports.engine.JasperReports</code> under the
        parameter <code class="literal">ProductsSubReport</code>. When configuring your
        Jasper view class, you can instruct Spring to load a report file and
        pass it into the JasperReports engine as a sub-report using the
        <code class="literal">subReportUrls</code> property:</p><pre class="programlisting">&lt;<span class="hl-tag">property</span> <span class="hl-attribute">name</span>=<span class="hl-value">"subReportUrls"</span>&gt;
    &lt;<span class="hl-tag">map</span>&gt;
        &lt;<span class="hl-tag">entry</span> <span class="hl-attribute">key</span>=<span class="hl-value">"ProductsSubReport"</span> <span class="hl-attribute">value</span>=<span class="hl-value">"/WEB-INF/reports/subReportChild.jrxml"</span>/&gt;
    &lt;<span class="hl-tag">/map</span>&gt;
&lt;<span class="hl-tag">/property</span>&gt;</pre><p>Here, the key of the <code class="interfacename">Map</code>
        corresponds to the name of the sub-report parameter in the report
        design file, and the entry is the URL of the report file. Spring will
        load this report file, compiling it if necessary, and pass it into
        the JasperReports engine under the given key.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="view-jasper-reports-subreports-config-datasources"></a>16.7.4.2&nbsp;Configuring Sub-Report Data Sources</h4></div></div></div><p>This step is entirely optional when using Spring to configure your
        sub-reports. If you wish, you can still configure the data source for
        your sub-reports using static queries. However, if you want Spring to
        convert data returned in your <code class="literal">ModelAndView</code> into
        instances of <code class="literal">JRDataSource</code> then you need to specify
        which of the parameters in your <code class="literal">ModelAndView</code> Spring
        should convert. To do this, configure the list of parameter names using
        the <code class="literal">subReportDataKeys</code> property of your chosen
        view class:</p><pre class="programlisting">&lt;<span class="hl-tag">property</span> <span class="hl-attribute">name</span>=<span class="hl-value">"subReportDataKeys"</span> <span class="hl-attribute">value</span>=<span class="hl-value">"SubReportData"</span>/&gt;</pre><p>Here, the key you supply <span class="bold"><strong>must</strong></span>
        correspond to both the key used in your <code class="literal">ModelAndView</code>
        and the key used in your report design file.</p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="view-jasper-reports-exporter-parameters"></a>16.7.5&nbsp;Configuring Exporter Parameters</h3></div></div></div><p>If you have special requirements for exporter configuration --
      perhaps you want a specific page size for your PDF report -- you can
      configure these exporter parameters declaratively in your Spring
      configuration file using the <code class="literal">exporterParameters</code>
      property of the view class. The <code class="literal">exporterParameters</code>
      property is typed as a <code class="interfacename">Map</code>. In your
      configuration the key of an entry should be the fully-qualified name of
      a static field that contains the exporter parameter definition, and the
      value of an entry should be the value you want to assign to the
      parameter. An example of this is shown below:</p><pre class="programlisting">&lt;<span class="hl-tag">bean</span> <span class="hl-attribute">id</span>=<span class="hl-value">"htmlReport"</span> <span class="hl-attribute">class</span>=<span class="hl-value">"org.springframework.web.servlet.view.jasperreports.JasperReportsHtmlView"</span>&gt;
  &lt;<span class="hl-tag">property</span> <span class="hl-attribute">name</span>=<span class="hl-value">"url"</span> <span class="hl-attribute">value</span>=<span class="hl-value">"/WEB-INF/reports/simpleReport.jrxml"</span>/&gt;
  &lt;<span class="hl-tag">property</span> <span class="hl-attribute">name</span>=<span class="hl-value">"exporterParameters"</span>&gt;
    &lt;<span class="hl-tag">map</span>&gt;
      &lt;<span class="hl-tag">entry</span> <span class="hl-attribute">key</span>=<span class="hl-value">"net.sf.jasperreports.engine.export.JRHtmlExporterParameter.HTML_FOOTER"</span>&gt;
        &lt;<span class="hl-tag">value</span>&gt;Footer by Spring!
          &amp;lt;/td&amp;gt;&amp;lt;td width="50%"&amp;gt;&amp;amp;nbsp; &amp;lt;/td&amp;gt;&amp;lt;/tr&amp;gt;
          &amp;lt;/table&amp;gt;&amp;lt;/body&amp;gt;&amp;lt;/html&amp;gt;
        &lt;<span class="hl-tag">/value</span>&gt;
      &lt;<span class="hl-tag">/entry</span>&gt;
    &lt;<span class="hl-tag">/map</span>&gt;
  &lt;<span class="hl-tag">/property</span>&gt;
&lt;<span class="hl-tag">/bean</span>&gt;</pre><p>Here you can see that the
      <code class="classname">JasperReportsHtmlView</code> is configured with an
      exporter parameter for
      <code class="literal">net.sf.jasperreports.engine.export.JRHtmlExporterParameter.HTML_FOOTER</code>
      which will output a footer in the resulting HTML.</p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="view-feeds"></a>16.8&nbsp;Feed Views</h2></div></div></div><p>Both <code class="classname">AbstractAtomFeedView</code> and
    <code class="classname">AbstractRssFeedView</code> inherit from the base class
    <code class="classname">AbstractFeedView</code> and are used to provide Atom and
    RSS Feed views respectfully. They are based on java.net's <a class="ulink" href="https://rome.dev.java.net" target="_top">ROME</a> project and are located in
    the package
    <code class="literal">org.springframework.web.servlet.view.feed</code>.</p><p><code class="classname">AbstractAtomFeedView</code> requires you to
    implement the <code class="methodname">buildFeedEntries()</code> method and
    optionally override the <code class="methodname">buildFeedMetadata()</code> method
    (the default implementation is empty), as shown below.</p><pre class="programlisting"><span class="hl-keyword">public</span> <span class="hl-keyword">class</span> SampleContentAtomView <span class="hl-keyword">extends</span> AbstractAtomFeedView {

  @Override
  <span class="hl-keyword">protected</span> <span class="hl-keyword">void</span> buildFeedMetadata(Map&lt;String, Object&gt; model, Feed feed,
      HttpServletRequest request) {
    <span class="hl-comment">// implementation omitted</span>
  }

  @Override
  <span class="hl-keyword">protected</span> List&lt;Entry&gt; buildFeedEntries(Map&lt;String, Object&gt; model,
      HttpServletRequest request, HttpServletResponse response)
      <span class="hl-keyword">throws</span> Exception {

    <span class="hl-comment">// implementation omitted</span>
  }
}</pre><p>Similar requirements apply for implementing
    <code class="classname">AbstractRssFeedView</code>, as shown below.</p><pre class="programlisting"><span class="hl-keyword">public</span> <span class="hl-keyword">class</span> SampleContentAtomView <span class="hl-keyword">extends</span> AbstractRssFeedView {

  @Override
  <span class="hl-keyword">protected</span> <span class="hl-keyword">void</span> buildFeedMetadata(Map&lt;String, Object&gt; model, Channel feed,
                                   HttpServletRequest request) {
    <span class="hl-comment">// implementation omitted</span>
  }

  @Override
  <span class="hl-keyword">protected</span> List&lt;Item&gt; buildFeedItems(Map&lt;String, Object&gt; model,
      HttpServletRequest request, HttpServletResponse response)
      <span class="hl-keyword">throws</span> Exception {
    <span class="hl-comment">// implementation omitted</span>
  }

}</pre><p>The <code class="methodname">buildFeedItems()</code> and
    <code class="methodname">buildFeedEntires()</code> methods pass in the HTTP request in case
    you need to access the Locale. The HTTP response is passed in only for the
    setting of cookies or other HTTP headers. The feed will automatically be
    written to the response object after the method returns.</p><p>For an example of creating an Atom view please refer to Alef
    Arendsen's SpringSource Team Blog <a class="ulink" href="http://blog.springsource.com/2009/03/16/adding-an-atom-view-to-an-application-using-springs-rest-support/" target="_top">entry</a>.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="view-xml-marshalling"></a>16.9&nbsp;XML Marshalling View</h2></div></div></div><p>The <code class="classname">MarhsallingView</code> uses an XML
    <code class="interfacename">Marshaller</code> defined in the
    <code class="classname">org.springframework.oxm</code> package to render the
    response content as XML. The object to be marshalled can be set explicitly
    using <code class="classname">MarhsallingView</code>'s
    <span class="property">modelKey</span> bean property. Alternatively, the view will
    iterate over all model properties and marshal only those types that are
    supported by the <code class="interfacename">Marshaller</code>. For more
    information on the functionality in the
    <code class="classname">org.springframework.oxm</code> package refer to the
    chapter <a class="link" href="oxm.html" title="14.&nbsp;Marshalling XML using O/X Mappers">Marshalling XML using O/X
    Mappers</a>.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="view-json-mapping"></a>16.10&nbsp;JSON Mapping View</h2></div></div></div><p>The <code class="classname">MappingJacksonJsonView</code> uses the Jackson 
  	library's <code class="classname">ObjectMapper</code> to render the response content 
  	as JSON. By default, the entire contents of the model map (with the exception 
  	of framework-specific classes) will be encoded as JSON. For cases where the 
  	contents of the map need to be filtered, users may specify a specific set of 
  	model attributes to encode via the <code class="literal">RenderedAttributes</code> 
  	property.</p><p>JSON mapping can be customized as needed through the use of Jackson's provided 
	annotations. When further control is needed, a custom 
	<code class="interfacename">ObjectMapper</code> can be injected through the 
	<code class="literal">ObjectMapper</code> property for cases where custom JSON 
	serializers/deserializers need to be provided for specific types.</p></div></div><!--Begin LoopFuse code--><script src="http://loopfuse.net/webrecorder/js/listen.js" type="text/javascript"></script><script type="text/javascript">
			_lf_cid = "LF_48be82fa";
			_lf_remora();
		</script><!--End LoopFuse code--><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="mvc.html">Prev</a>&nbsp;</td><td width="20%" align="center"><a accesskey="u" href="spring-web.html">Up</a></td><td width="40%" align="right">&nbsp;<a accesskey="n" href="web-integration.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">15.&nbsp;Web MVC framework&nbsp;</td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top">&nbsp;17.&nbsp;Integrating with other web frameworks</td></tr></table></div><!-- Begin 2nd Google code - a mod -->
<script type="text/javascript">
var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www.");document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E"));</script>
<script type="text/javascript">
var OrgTracker = _gat._getTracker("UA-2728886-2"); OrgTracker._setDomainName("none");
OrgTracker._setAllowLinker(true);
OrgTracker._trackPageview();
</script>
 <!-- End 2nd Google code -->


<script type="text/javascript">

function detectLastFrame() {
   var thisF = this.window;
   var allF = parent.top.frames;
   return allF[allF.length - 1] == thisF; }

// Only inject the following code if this is a normal page or the last // frame of a frameset.
if (parent.top.frames.length == 0 || detectLastFrame()) {
    // Inject the SpringSource search widget too.
    document.write(unescape("%3Cscript src='http://search.springsource.org/widget/searchtool.js' type='text/javascript'%3E%3C/script%3E"));
    // Inject the Eloqua code
    document.write(unescape("%3Cscript src='/elqNow/elqCfg.js' type='text/javascript'%3E%3C/script%3E"));
    document.write(unescape("%3Cscript src='/elqNow/elqImg.js' type='text/javascript'%3E%3C/script%3E"));

}
</script>
</body>
</html>